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Foreword 


Microsoft’s  MS-DOS  is  the  most  popular  piece  of  software  in  the  world.  It  runs  on  more 
than  10  million  personal  computers  worldwide  and  is  the  foundation  for  at  least  20,000 
applications — the  largest  set  of  applications  in  any  computer  environment.  As  an  industry 
standard  for  the  family  of  8086-based  microcomputers,  MS-DOS  has  had  a  central  role  in 
the  personal  computer  revolution  and  is  the  most  significant  and  enduring  factor  in  fur¬ 
thering  Microsoft’s  original  vision — a  computer  for  every  desktop  and  in  every  home.  The 
challenge  of  maintaining  a  single  operating  system  over  the  entire  range  of  8086-based 
microcomputers  and  applications  is  incredible,  but  Microsoft  has  been  committed  to  meet¬ 
ing  this  challenge  since  the  release  of  MS-DOS  in  1981.  The  true  measure  of  our  success 
in  this  effort  is  MS-DOS’s  continued  prominence  in  the  microcomputer  industry. 

Since  MS-DOS’s  creation,  more  powerful  and  much-improved  computers  have  entered  the 
marketplace,  yet  each  new  version  of  MS-DOS  reestablishes  its  position  as  the  foundation 
for  new  applications  as  well  as  for  old.  To  explain  this  extraordinary  prominence,  we  must 
look  to  the  origins  of  the  personal  computer  industry.  The  three  most  significant  factors  in 
the  creation  of  MS-DOS  were  the  compatibility  revolution,  the  development  of  Microsoft 
BASIC  and  its  widespread  acceptance  by  the  personal  computer  industry,  and  IBM’s  deci¬ 
sion  to  build  a  computer  that  incorporated  l6-bit  technology. 

The  compatibility  revolution  began  with  the  Intel  8080  microprocessor.  This  technolog¬ 
ical  breakthrough  brought  unprecedented  opportunities  in  the  emerging  microcomputer 
industry,  promising  continued  improvements  in  power,  speed,  and  cost  of  desktop  com¬ 
puting.  In  the  minicomputer  market,  every  hardware  manufacturer  had  its  own  special 
instruction  set  and  operating  system,  so  software  developed  for  a  specific  machine  was  in¬ 
compatible  with  the  machines  of  other  hardware  vendors.  This  specialization  also  meant 
tremendous  duplication  of  effort — each  hardware  vendor  had  to  write  language  compilers, 
databases,  and  other  development  tools  to  fit  its  particular  machine.  Microcomputers 
based  on  the  8080  microprocessor  promised  to  change  all  this  because  different  manu¬ 
facturers  would  buy  the  same  chip  with  the  same  instruction  set. 

From  1975  to  1981  (the  8-bit  era  of  microcomputing),  Microsoft  convinced  virtually 
every  personal  computer  manufacturer — Radio  Shack,  Commodore,  Apple,  and  dozens 
of  others — to  build  Microsoft  BASIC  into  its  machines.  For  the  first  time,  one  common  lan¬ 
guage  cut  across  all  hardware  vendor  lines.  The  success  of  our  BASIC  demonstrated  the 
advantages  of  compatibility:  To  their  great  benefit,  users  were  finally  able  to  move  appli¬ 
cations  from  one  vendor’s  machine  to  another. 

Most  machines  produced  during  this  early  period  did  not  have  a  built-in  disk  drive. 
Gradually,  however,  floppy  disks,  and  later  fixed  disks,  became  less  expensive  and  more 
common,  and  a  number  of  disk-based  programs,  including  WordStar  and  dBASE,  entered 
the  market.  A  standard  disk  operating  system  that  could  accommodate  these  develop¬ 
ments  became  extremely  important,  leading  Lifeboat,  Microsoft,  and  Digital  Research  all  to 
support  CP/M-80,  Digital  Research’s  8080  DOS. 
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The  8-bit  era  proved  the  importance  of  having  a  multiple-manufacturer  standard  that 
permitted  the  free  interchange  of  programs.  It  was  important  that  software  designed  for 
the  new  l6-bit  machines  have  this  same  advantage.  No  personal  computer  manufacturer  in 
1980  could  have  predicted  with  any  accuracy  how  quickly  a  third-party  software  industry 
would  grow  and  get  behind  a  strong  standard — a  standard  that  would  be  the  software 
industry’s  lifeblood.  The  intricacies  of  how  MS-DOS  became  the  most  common  l6-bit 
operating  system,  in  part  through  the  work  we  did  for  IBM,  is  not  the  key  point  here.  The 
key  point  is  that  it  was  inevitable  for  a  popular  operating  system  to  emerge  for  the  l6-bit 
machine,  just  as  Microsoft’s  BASIC  had  prevailed  on  the  8-bit  systems. 

It  was  overwhelmingly  evident  that  the  personal  computer  had  reached  broad  acceptance 
in  the  market  when  Time  in  1982  named  the  personal  computer  “Man  of  the  Year.”  MS- 
DOS  was  integral  to  this  acceptance  and  popularity,  and  we  have  continued  to  adapt 
MS-DOS  to  support  more  powerful  computers  without  sacrificing  the  compatibility  that  is 
essential  to  keeping  it  an  industry  standard.  The  presence  of  the  80386  microprocessor 
guarantees  that  continued  investments  in  Intel-architecture  software  will  be  worthwhile. 

Our  goal  with  The  MS-DOS  Encyclopedia  is  to  provide  the  most  thorough  and  accessible 
resource  available  anywhere  for  MS-DOS  programmers.  The  length  of  this  book  is  many 
times  greater  than  the  source  listing  of  the  first  version  of  MS-DOS — evidence  of  the 
growing  complexity  and  sophistication  of  the  operating  system.  The  encyclopedia  will  be 
especially  useful  to  software  developers  faced  with  preserving  continuity  yet  enhancing 
the  portability  of  their  applications. 

Our  thriving  industry  is  committed  to  exploiting  the  advantages  offered  by  the  protected 
mode  introduced  with  the  80286  microprocessor  and  the  virtual  mode  introduced  with  the 
80386  microprocessor.  MS-DOS  will  continue  to  play  an  integral  part  in  this  effort.  Faster 
and  more  powerful  machines  running  Microsoft  OS/2  mean  an  exciting  future  of  multi¬ 
tasking  systems,  networking,  improved  levels  of  data  protection,  better  hardware  memory 
management  for  multiple  applications,  stunning  graphics  systems  that  can  display  an  inno¬ 
vative  graphical  user  interface,  and  communication  subsystems.  MS-DOS  version  3,  which 
runs  in  real  mode  on  80286-based  and  80386-based  machines,  is  a  vital  link  in  the  Family 
API  of  OS/2.  Users  will  continue  to  benefit  from  our  commitment  to  improved  operating- 
system  performance  and  usability  as  the  future  unfolds. 


Bill  Gates 
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Preface 


In  the  space  of  six  years,  MS-DOS  has  become  the  most  widely  used  computer  operating 
system  in  the  world,  running  on  more  than  10  million  machines.  It  has  grown,  matured, 
and  stabili2ed  into  a  flexible,  easily  extendable  system  that  can  support  networking, 
graphical  user  interfaces,  nearly  any  peripheral  device,  and  even  CD  ROMs  containing 
massive  amounts  of  on-line  information.  MS-DOS  will  be  with  us  for  many  years  to  come 
as  the  platform  for  applications  that  run  on  low-cost,  8086/8088-based  machines. 

Not  surprisingly,  the  success  of  MS-DOS  has  drawn  many  writers  and  publishers  into  its 
orbit.  The  number  of  books  on  MS-DOS  and  its  commands,  languages,  and  applications 
dwarfs  the  list  of  titles  for  any  other  operating  system.  Why,  then,  yet  another  book  on 
MS-DOS?  And  what  can  we  say  about  the  operating  system  that  has  not  been  said  already? 

First,  we  have  written  and  edited  The  MS-DOS  Encyclopedia  with  one  audience  in  mind: 
the  community  of  working  programmers.  We  have  therefore  been  free  to  bypass  elemen¬ 
tary  subjects  such  as  the  number  of  bits  in  a  byte  and  the  interpretation  of  hexadecimal 
numbers.  Instead,  we  have  emphasized  detailed  technical  explanations,  working  code  ex¬ 
amples  that  can  be  adapted  and  incorporated  into  new  applications,  and  a  systems  view  of 
even  the  most  common  MS-DOS  commands  and  utilities. 

Second,  because  we  were  not  subject  to  size  restrictions,  we  have  explored  topics  in  depth 
that  other  MS-DOS  books  mention  only  briefly,  such  as  exception  and  error  handling, 
interrupt-driven  communications,  debugging  strategies,  memory  management,  and  install¬ 
able  device  drivers.  We  have  commissioned  definitive  articles  on  the  relocatable  object 
modules  generated  by  Microsoft  language  translators,  the  operation  of  the  Microsoft  Ob¬ 
ject  Linker,  and  terminate-and-stay-resident  utilities.  We  have  even  interviewed  the  key 
developers  of  MS-DOS  and  drawn  on  their  files  and  bulletin  boards  to  offer  an  entertain¬ 
ing,  illustrated  account  of  the  origins  of  Microsoft’s  standard-setting  operating  system. 

Finally,  by  combining  the  viewpoints  and  experience  of  non-Microsoft  programmers  and 
writers,  the  expertise  and  resources  of  Microsoft  software  developers,  and  the  publishing 
know-how  of  Microsoft  Press,  we  have  assembled  a  unique  and  comprehensive  reference 
to  MS-DOS  services,  commands,  directives,  and  utilities.  In  many  instances,  the  manu¬ 
scripts  have  been  reviewed  by  the  authors  of  the  Microsoft  tools  described. 

We  have  made  every  effort  during  the  creation  of  this  book  to  ensure  that  its  contents  are 
timely  and  trustworthy.  In  a  work  of  this  size,  however,  it  is  inevitable  that  errors  and  omis¬ 
sions  will  occur.  If  you  discover  any  such  errors,  please  bring  them  to  our  attention  so  that 
they  can  be  repaired  in  future  printings  and  thus  aid  your  fellow  programmers.  To  this 
end,  Microsoft  Press  has  established  a  bulletin  board  on  MCI  Mail  for  posting  corrections 
and  comments.  Please  refer  to  page  xvi  for  more  information. 


Ray  Duncan 
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updates  to  The  MS-DOS  Encyclopedia 

Periodically,  the  staff  of  The  MS-DOS  Encyclopedia  will  publish  updates  containing 
clarifications  or  corrections  to  the  information  presented  in  this  current  edition.  To  ob¬ 
tain  information  about  receiving  these  updates,  please  check  the  appropriate  box  on  the 
business  reply  card  in  the  back  of  this  book,  or  send  your  name  and  address  to:  MS-DOS 
Encyclopedia  Update  Information,  c/o  Microsoft  Press,  I6OII NE  36th  Way,  Box  97017, 
Redmond,  WA  98073-9717. 

Bulletin  Board  Service 

Microsoft  Press  is  sponsoring  a  bulletin  board  on  MCI  Mail  for  posting  and  receiving  cor¬ 
rections  and  comments  for  The  MS-DOS  Encyclopedia,  To  use  this  service,  log  on  to  MCI 
Mail  and,  after  receiving  the  prompt,  type 

VIEW  <Enter> 

The  Bulletin  Board  name:  prompt  will  be  displayed.  Then  type 

MSPRESS  <Enter> 

to  connect  to  the  Microsoft  Press  bulletin  board.  A  list  of  the  individual  Microsoft  Press 
bulletin  boards  will  be  displayed;  simply  choose  MSPress  DOSENCY to  enter  the  en¬ 
cyclopedia’s  bulletin  board. 


Special  Companion  Disk  Offer 

Microsoft  Press  has  created  a  set  of  valuable,  time  saving  companion  disks  to  The  MS-DOS 
Encyclopedia/I\\QY  contain  the  routines  and  functional  programs  that  are  listed  through¬ 
out  this  book — thousands  of  lines  of  executable  code.  Conveniently  organized,  these 
disks  will  save  you  hours  of  typing  time  and  allow  you  to  start  using  the  code  immediately. 
The  companion  disks  are  only  available  directly  from  Microsoft  Press.  To  order,  use  the 
special  bind-in  card  in  the  back  of  the  book  or  send  $49.95  for  each  set  of  disks,  plus  sales 
tax  if  applicable  and  $5.50  per  disk  for  domestic  postage  and  handling,  $8.00  per  disk  for 
foreign  orders,  to:  Microsoft  Press,  Attn:  Companion  Disk  Offer,  21919  20th  Ave.  S.E.,  Box 
3011,  Bothell,  WA  98041-3011.  Please  specify  5.25-inch  or  3.5-inch  format.  Payment  must  be 
in  U.S.  funds.  You  may  pay  by  check  or  money  order  (payable  to  Microsoft  Press),  or  by 
American  Express,  VISA,  or  MasterCard;  please  include  your  credit  card  number  and  ex¬ 
piration  date.  All  domestic  orders  are  shipped  2nd  day  air  upon  receipt  of  order  by 
Microsoft. 

CA  residents  5%  plus  local  option  tax,  CT  7.5%,  FL  6%,  MA  5%,  MN  6%,  MO  4.225%,  NY  4%  plus  local 
option  tax,  WA  State  7.8%. 
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Introduction 


The  MS-DOS  Encyclopedia  is  the  most  comprehensive  reference  work  available  on 
Microsoft’s  industry-standard  operating  system.  Written  for  experienced  microcomputer 
users  and  programmers,  it  contains  detailed,  version-specific  information  on  all  the 
MS-DOS  commands,  utilities,  and  system  calls,  plus  articles  by  recognized  experts  in 
specialized  areas  of  MS-DOS  programming.  This  wealth  of  material  is  organized  into 
major  topic  areas,  each  with  a  format  suited  to  its  content.  Special  typographic  conven¬ 
tions  are  also  used  to  clarify  the  material. 


Organization  of  the  Book 

The  MS-DOS  Encyclopedia  is  organized  into  five  major  sections,  plus  appendixes.  Each 
section  has  a  unique  internal  organization;  explanatory  introductions  are  included  where 
appropriate. 

Section  I,  The  Development  of  MS-DOS,  presents  the  history  of  Microsoft’s  standard¬ 
setting  operating  system  from  its  immediate  predecessors  through  version  3.2.  Numerous 
photographs,  anecdotes,  and  quotations  are  included. 

Section  II,  Programming  in  the  MS-DOS  Environment,  is  divided  into  five  parts:  Structure 
of  MS-DOS,  Programming  for  MS-DOS,  Customizing  MS-DOS,  Directions  of  MS-DOS,  and 
Programming  Tools.  Each  part  contains  several  articles  by  acknowledged  experts  on  these 
topics.  The  articles  include  numerous  figures,  tables,  and  programming  examples  that  pro¬ 
vide  detail  about  the  subject. 

Section  III,  User  Commands,  presents  all  the  MS-DOS  internal  and  external  commands  in 
alphabetic  order,  including  ANSI.SYS,  BATCH,  CONFIG.SYS,  DRIVER.SYS,  EDLIN, 
RAMDRIVE.SYS,  and  VDISK.SYS.  Each  command  is  presented  in  a  structure  that  allows 
the  experienced  user  to  quickly  review  syntax  and  restrictions  on  variables;  the  less- 
experienced  user  can  refer  to  the  detailed  discussion  of  the  command  and  its  uses. 

Section  IV,  Programming  Utilities,  uses  the  same  format  as  the  User  Commands  section  to 
present  the  Microsoft  programming  aids,  including  the  DEBUG,  SYMDEB,  and  CodeView 
debuggers.  Although  some  of  these  utilities  are  supplied  only  with  Microsoft  language 
products  and  are  not  included  on  the  MS-DOS  system  or  supplemental  disks,  their  use  is 
intrinsic  to  programming  for  MS-DOS,  and  they  are  therefore  included  to  create  a  com¬ 
prehensive  reference. 
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Section  V,  System  Calls,  documents  Interrupts  20H  through  27H  and  Interrupt  2FH.  The 
Interrupt  21H  functions  are  listed  in  individual  entries.  This  section,  like  the  User  Com¬ 
mands  and  Programming  Utilities  sections,  presents  a  quick  review  of  usage  for  the  ex¬ 
perienced  user  and  also  provides  extensive  notes  for  the  less-experienced  programmer. 

The  15  appendixes  provide  quick-reference  materials,  including  a  summary  of  MS-DOS 
version  3.3,  the  segmented  (new)  .EXE  file  header  format,  an  object  file  dump  utility,  and 
the  Intel  hexadecimal  object  file  format.  Much  of  this  material  is  organized  into  tables  or 
bulleted  lists  for  ease  of  use. 

The  book  includes  two  indexes — one  organized  by  subject  and  one  organized  by  com¬ 
mand  name  or  system-call  number.  The  subject  index  provides  comprehensive  references 
to  the  indexed  topic;  the  command  index  references  only  the  major  entry  for  the  com¬ 
mand  or  system  call. 


Program  Listings 

The  MS-DOS  Encyclopedia  contains  numerous  program  listings  in  assembly  language,  C, 
and  QuickBASIC,  all  designed  to  run  on  the  IBM  PC  family  and  compatibles.  Most  of  these 
programs  are  complete  utilities;  some  are  routines  that  can  be  incorporated  into  function¬ 
ing  programs.  Vertical  ellipses  are  often  used  to  indicate  where  additional  code  would  be 
supplied  by  the  user  to  create  a  more  functional  program.  All  program  listings  are  heavily 
commented  and  are  essentially  self-documenting. 

The  programs  were  tested  using  the  Microsoft  Macro  Assembler  (MASM)  version  4.0,  the 
Microsoft  C  Compiler  version  4.0,  or  the  Microsoft  QuickBASIC  Compiler  version  2.0. 

The  functional  programs  and  larger  routines  are  also  available  on  disk.  Instructions  for 
ordering  are  on  the  page  preceding  this  introduction  and  on  the  mail-in  card  bound  into 
this  volume. 


Typography  and  Terminology 

Because  The  MS-DOS  Encyclopedia  was  designed  for  an  advanced  audience,  the  reader 
generally  will  be  familiar  with  the  notation  and  typographic  conventions  used  in  this 
volume.  However,  for  ease  of  use,  a  few  special  conventions  should  be  noted. 

Typographic  conventions 

Capital  letters  are  used  for  MS-DOS  internal  and  external  commands  in  text  and  syntax 
lines.  Capital  letters  are  also  used  for  filenames  in  text. 
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Italic  font  indicates  user-supplied  variable  names,  procedure  names  in  text,  parameters 
whose  values  are  to  be  supplied  by  the  user,  reserved  words  in  the  C  programming  lan¬ 
guage,  messages  and  return  values  in  text,  and,  occasionally,  emphasis. 

A  typographic  distinction  is  made  between  lowercase  1  and  the  numeral  1  in  both  text  and 
program  listings. 

Cross-references  appear  in  the  form  SECTION  NAME:  Part  Name,  Command  name,  or  In¬ 
terrupt  NUMBER:  Article  Name  or  Function  Number. 

Color  indicates  user  input  and  program  examples. 

Terminology 

Although  not  an  official  IBM  name,  the  term  PC-DOS  in  this  book  means  the  IBM  imple¬ 
mentation  of  MS-DOS.  If  PC-DOS  is  referenced  and  the  information  differs  from  that  for 
the  related  MS-DOS  version,  the  PC-DOS  version  number  is  included.  To  avoid  confusion, 
the  term  DOS  is  never  used  without  a  modifier. 

The  names  of  special  function  keys  are  spelled  as  they  are  shown  on  the  IBM  PC  keyboard. 
In  particular,  the  execute  key  is  cdled  Enter,  not  Return.  When  <Enter>  is  included  in  a 
user-entry  line,  the  user  is  to  press  the  Enter  key  at  the  end  of  the  line. 

The  common  key  combinations,  such  as  Ctrl-C  and  Ctrl-Z,  appear  in  this  form  when  the 
actual  key  to  be  pressed  is  being  discussed  but  are  written  as  Control-C,  Control-Z,  and  so 
forth  when  the  resulting  code  is  the  true  reference.  Thus,  an  article  might  reference  the 
Control-C  handler  but  state  that  it  is  activated  when  the  user  presses  Ctrl-C. 

Unless  specifically  indicated,  hexadecimal  numbers  are  used  throughout.  These  numbers 
are  always  followed  by  the  designation  H  Qi  in  the  code  portions  of  program  listings). 
Ranges  of  hexadecimal  values  are  indicated  with  a  dash — for  example,  07-0AH. 

The  notation  (more)  appears  in  italic  at  the  bottom  of  program  listings  and  tables  that  are 
continued  on  the  next  page.  The  complete  caption  or  table  title  appears  on  the  first  page 
of  a  continued  element  and  is  designated  Continued  on  subsequent  pages. 
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The  Development  of  MS-DOS 


To  many  people  who  use  personal  computers,  MS-DOS  is  the  key  that  unlocks  the  power 
of  the  machine.  It  is  their  most  visible  connection  to  the  hardware  hidden  inside  the 
cabinet,  and  it  is  through  MS-DOS  that  they  can  run  applications  and  manage  disks  and 
disk  files.  ^ 

In  the  sense  that  it  opens  the  door  to  doing  work  with  a  personal  computer,  MS-DOS  is 
indeed  a  key,  and  the  lock  it  fits  is  the  Intel  8086  family  of  microprocessors.  MS-DOS  and 
the  chips  it  works  with  are,  in  fact,  closely  connected — so  closely  that  the  story  of 
MS-DOS  is  really  part  of  a  larger  history  that  encompasses  not  only  an  operating  system 
but  also  a  microprocessor  and,  in  retrospect,  part  of  the  explosive  growth  of  personal 
computing  itself. 

Chronologically,  the  history  of  MS-DOS  can  be  divided  into  three  parts.  First  came  the 
formation  of  Microsoft  and  the  events  preceding  Microsoft’s  decision  to  develop  an 
operating  system.  Then  came  the  creation  of  the  first  version  of  MS-DOS.  Finally,  there  is 
the  continuing  evolution  of  MS-DOS  since  its  release  in  1981. 

Much  of  the  story  is  based  on  technical  developments,  but  dates  and  facts  alone  do  not 
provide  an  adequate  look  at  the  past.  Many  people  have  been  involved  in  creating  MS-DOS 
and  directing  the  lines  along  which  it  continues  to  grow.  To  the  extent  that  personal  opin¬ 
ions  and  memories  are  appropriate,  they  are  included  here  to  provide  a  fuller  picture  of 
the  origin  and  development  of  MS-DOS. 


Before  MS-DOS 

The  role  of  International  Business  Machines  Corporation  in  Microsoft’s  decision  to  create 
MS-DOS  has  been  well  publicized.  But  events,  like  inventions,  always  build  on  prior  ac¬ 
complishments,  and  in  this  respect  the  roots  of  MS-DOS  reach  farther  back,  to  four  hard¬ 
ware  and  software  developments  of  the  1970s:  Microsoft’s  disk-based  and  stand-alone 
versions  of  BASIC,  Digital  Research’s  CP/M-80  operating  system,  the  emergence  of  the 
8086  chip,  and  a  disk  operating  system  for  the  8086  developed  by  Tim  Paterson  at  a  hard¬ 
ware  company  called  Seattle  Computer  Products. 

Microsoft  and  BASIC 

On  the  surface,  BASIC  and  MS-DOS  might  seem  to  have  little  in  common,  but  in  terms  of 
file  management,  MS-DOS  is  a  direct  descendant  of  a  Microsoft  version  of  BASIC  called 
Stand-alone  Disk  BASIC. 

Before  Microsoft  even  became  a  company,  its  founders,  Paul  Allen  and  Bill  Gates,  de¬ 
veloped  a  version  of  BASIC  for  a  revolutionary  small  computer  named  the  Altair,  which 
was  introduced  in  January  1975  by  Micro  Instrumentation  Telemetry  Systems  (MITS)  of 
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TheAltair.  Christened  one  evening  shortly  before  its  appearance  on  the  cover  of  Popular  Electronics 
magazine,  the  computer  was  named for  the  night’s  destination  of  the  starship  Enterprise.  The  photograph 
clearly  shows  the  input  switches  on  the  front  panel  of  the  cabinet. 


Albuquerque,  New  Mexico.  Though  it  has  long  been  eclipsed  by  other,  more  powerful 
makes  and  models,  the  Altair  was  the  first  “personal”  computer  to  appear  in  an  environ¬ 
ment  dominated  by  minicomputers  and  mainframes.  It  was,  simply,  a  metal  box  with  a 
panel  of  switches  and  lights  for  input  and  output,  a  power  supply,  a  motherboard  with  18 
slots,  and  two  boards.  One  board  was  the  central  processing  unit,  with  the  8-bit  Intel  8080 
microprocessor  at  its  heart;  the  other  board  provided  256  bytes  of  random-access  memory. 
This  miniature  computer  had  no  keyboard,  no  monitor,  and  no  device  for  permanent 
storage,  but  it  did  possess  one  great  advantage:  a  price  tag  of  $397. 

Now,  given  the  hindsight  of  a  little  more  than  a  decade  of  microcomputing  history,  it  is 
easy  to  see  that  the  Altair’s  combination  of  small  size  and  affordability  was  the  thin  edge 
of  a  wedge  that,  in  just  a  few  years,  would  move  everyday  computing  power  away  from 
impersonal  monoliths  in  climate-controlled  rooms  and  onto  the  desks  of  millions  of 
people.  In  1975,  however,  the  computing  environment  was  still  primarily  a  matter  of  data 
processing  for  specialists  rather  than  personal  computing  for  everyone.  Thus  when  4  KB 
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InteVs  4004,  8008,  and  8080  chips.  At  the  top  left  is  the  4-bit  4004,  which  was  named  for  the  approximate 
number  of  old-fashioned  transistors  it  replaced.  At  the  bottom  left  is  the  8-bit  8008,  which  addressed  16  KB  of 
memory;  this  was  the  chip  used  in  the  Traf-O-Data  tape-reader  built  by  Paul  Gilbert.  At  the  right  is  the  8080, 
a  faster  8-bit  chip  that  could  address  64  KB  of  memory.  The  brain  of  the  MITS  Altair,  the  8080  was,  in  many 
respects,  the  chip  on  which  the  personal  computing  industry  was  built.  The  4004  and  8008  chips  were 
developed  early  in  the  1970s;  the  8080  appeared  in  1974. 

memory  expansion  boards  became  available  for  the  Altair,  the  software  needed  most  by  its 
users  was  not  a  word  processor  or  a  spreadsheet,  but  a  programming  language  —  and  the 
language  first  developed  for  it  was  a  version  of  BASIC  written  by  Bill  Gates  and  Paul  Allen. 

Gates  and  Allen  had  become  friends  in  their  teens,  while  attending  Lakeside  School  in 
Seattle.  They  shared  an  intense  interest  in  computers,  and  by  the  time  Gates  was  in  the 
tenth  grade,  they  and  another  friend  named  Paul  Gilbert  had  formed  a  company  called 
Traf-O-Data  to  produce  a  machine  that  automated  the  reading  of  l6-channel,  4-digit, 
binary-coded  decimal  (BCD)  tapes  generated  by  traffic-monitoring  recorders.  This  ma¬ 
chine,  built  by  Gilbert,  was  based  on  the  Intel  8008  microprocessor,  the  predecessor 
of  the  8080  in  the  Altair. 
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HOW  TO  “READ”  FM  TUHER  SPECIFICATIONS 

Popular  Electronics 

^  WORLDS  LARGEST-SELLING  ELECTRONICS  MAGAZINE  JANUARY  1975/ 75<P 


PROJECT  BREAKTHROUGH! 

World's  First  Minicomputer  Kit 
to  Ri^l  Commercial  Models... 
"ALTAI  R  8800"  save  over  $1000 


1  ALTAIR  S800  | 

■  •  >  *  • .  • .  • 

L 

X  MrA  VVVr- 

ALSO  IN  THIS  ISSUE: 


•  An  Under-$90  Scientific  Calculator  Project 

•  CCD’s-TV  Camera  Tube  Successor? 

•  Thyristor-Controlled  Photoflashers 


TEST  REPORTS  I 


Technics  200  Speaker  System 
Pioneer  RT-lOU  Open-Reel  Recorder 
Tram  Diamond-40  CB  AM  Transceiver 
Edmund  Scientific  "Kirlian"  Photo  Kit 
Hewlett-Packard  5381  Frequency  Counter 


The  January  1975  cover  of  Popular 
Electronics  magazine,  featuring  the 
machine  that  caught  the  imaginations 
of  thousands  of  like-minded  electron¬ 
ics  enthusiasts  —  among  them,  Paul 
Allen  and  Bill  Gates. 


Although  it  was  too  limited  to  serve  as  the  central  processor  for  a  general-purpose  compu¬ 
ter,  the  8008  was  undeniably  the  ancestor  of  the  8080  as  far  as  its  architecture  and  instruc¬ 
tion  set  were  concerned.  Thus  Traf-O-Data’s  work  with  the  8008  gave  Gates  and  Allen  a 
head  start  when  they  later  developed  their  version  of  BASIC  for  the  Altair. 

Paul  Allen  learned  of  the  Altair  from  the  cover  story  in  the  January  1975  issue  of  Popular 
Electronics  magazine.  Allen,  then  an  employee  of  Honeywell  in  Boston,  convinced  Gates, 
a  student  at  Harvard  University,  to  develop  a  BASIC  for  the  new  computer.  The  two  wrote 
their  version  of  BASIC  for  the  8080  in  six  weeks,  and  Allen  flew  to  New  Mexico  to  demon¬ 
strate  the  language  for  MITS.  The  developers  gave  themselves  the  company  name  of 
Microsoft  and  licensed  their  BASIC  to  MITS  as  Microsoft’s  first  product. 

Though  not  a  direct  forerunner  of  MS-DOS,  Altair  BASIC,  like  the  machine  for  which  it  was 
developed,  was  a  landmark  product  in  the  history  of  personal  computing.  On  another 
level,  Altair  BASIC  was  also  the  first  link  in  a  chain  that  led,  somewhat  circuitously,  to  Tim 
Paterson  and  the  disk  operating  system  he  developed  for  Seattle  Computer  Products  for 
the  8086  chip. 
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OCMPUICT  NOIES/JULY,  1975 


Loading  Software 

Software  from  MITS  will  be  pro¬ 
vided  in  a  checksummed  format. 

There  will  be  a  bootstrap  loader 
that  you  key  in  manually  (less  than 
25  bytes).  This  will  read  a  eheck- 
suB  loader  (the  'bin*  loader)  which 
will  be  about  120  bytes. 

For  audio  cassette  loading  the 
bootstrap  and  checksum  loaders  will 
be  longer.  All  of  this  will  be  ex¬ 
plained  in  detail  in  a  cover  package 
that  will  go  out  with  all  software. 

For  loading  non-checksummed 
paper  tapes  here  is  a  short  program: 

STKLOC:  Dtf  GETNCW 

(2  bytes-ll  low  byte  of 

GCTNCW  address 
#2  high  byte  of 
GCTNCW  address) 


START:  LXI  H,0 

GCTNCW;  LXI  SP,  STKLOC 

IN  <flag-input  channel> 

RAL  ;get  input  ready  bit 
RNZ  ;ready? 

IN  <data-input  channel> 
CHGLOC:  CPI  <043  s  INX  B> 

RNZ 
INR  A 

STA  CHGLOC 
RCT 

(22  bytes) 

Punch  a  paper  tape  with  leader, 
a  043  start  byte,  the  byte  to  be 
stored  at  loc  0,  the  byte  to  be 
stored  at  1,  -  -  -  etc.  Start  at 
START,  making  sure  the  memory  the 
loader  is  in  is  unprotected.  Make 
sure  you  don’t  wipe  out  the  loader 
by  loading  on  top  of  it. 

To  run  this  again  change  CHGLOC 
back  to  CPI  -  376. 


On  the  left,  Bill  Gates’s  original  handwritten  notes  describing  memory  configuration  for  Altair  BASIC.  On 
the  right,  a  short  bootstrap  program  written  by  Gates for  Altair  users;  published  in  the fuly  1975  edition  of  the 
MITS  user  newsletter.  Computer  Notes. 


From  paper  tape  to  disk 

Gates  and  Allen’s  early  BASIC  for  the  Altair  was  loaded  from  paper  tape  after  the  bootstrap 
to  load  the  tape  was  entered  into  memory  by  flipping  switches  on  the  front  panel  of  the 
computer.  In  late  1975,  however,  MITS  decided  to  release  a  floppy-disk  system  for  the 
Altair — the  first  retail  floppy-disk  system  on  the  market.  As  a  result,  in  February  1976 
Allen,  by  then  Director  of  Software  for  MITS,  asked  Gates  to  write  a  disk-based  version  of 
Altair  BASIC.  The  Altair  had  no  operating  system  and  hence  no  method  of  managing  files, 
so  the  disk  BASIC  would  have  to  include  some  file-management  routines.  It  would,  in 
effect,  have  to  function  as  a  rudimentary  operating  system. 
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Microsoft,  1978,  Albuquerque, 

New  Mexico.  Top  row,  left  to  right: 
Steve  Wood,  Bob  Wallace,  Jim  Lane. 
Middle  row,  left  to  right:  Bob  O’Rear, 
Bob  Greenberg,  Marc  McDonald, 
Gordon  Letwin.  Bottom  row,  left  to 
right:  Bill  Gates,  Andrea  Lewis, 
Marla  Wood,  Paul  Allen. 


Gates,  still  at  Harvard  University,  agreed  to  write  this  version  of  BASIC  for  MITS.  He  went 
to  Albuquerque  and,  as  has  often  been  recounted,  checked  into  the  Hilton  Hotel  with  a 
stack  of  yellow  legal  pads.  Five  days  later  he  emerged,  yellow  pads  filled  with  the  code  for 
the  new  version  of  BASIC.  Arriving  at  MITS  with  the  code  and  a  request  to  be  left  alone. 
Gates  began  typing  and  debugging  and,  after  another  five  days,  had  Disk  BASIC  running 
on  the  Altair. 

This  disk-based  BASIC  marked  Microsoft’s  entry  into  the  business  of  languages  for  per¬ 
sonal  computers  —  not  only  for  the  MITS  Altair,  but  also  for  such  companies  as  Data 
Terminals  Corporation  and  General  Electric.  Along  the  way,  Microsoft  BASIC  took  on 
added  features,  such  as  enhanced  mathematics  capabilities,  and,  more  to  the  point  in 
terms  of  MS-DOS,  evolved  into  Stand-alone  Disk  BASIC,  produced  for  NCR  in  1977. 

Designed  and  coded  by  Marc  McDonald,  Stand-alone  Disk  BASIC  included  a  file- 
management  scheme  called  the  FAT,  or  file  allocation  table  that  used  a  linked  list  for  man¬ 
aging  disk  files.  The  FAT,  born  during  one  of  a  series  of  discussions  between  McDonald 
and  Bill  Gates,  enabled  disk-allocation  information  to  be  kept  in  one  location,  with 
“chained”  references  pointing  to  the  actual  storage  locations  on  disk.  Fast  and  flexible, 
this  file-management  strategy  was  later  used  in  a  stand-alone  version  of  BASIC  for  the  8086 
chip  and  eventually,  through  an  operating  system  named  M-DOS,  became  the  basis  for  the 
file-handling  routines  in  MS-DOS. 

M-DOS 

During  1977  and  1978,  Microsoft  adapted  both  BASIC  and  Microsoft  FORTRAN  for  an 
increasingly  popular  8-bit  operating  system  called  CP/M.  At  the  end  of  1978,  Gates  and 
Allen  moved  Microsoft  from  Albuquerque  to  Bellevue,  Washington.  The  company  con¬ 
tinued  to  concentrate  on  programming  languages,  producing  versions  of  BASIC  for  the 
6502  and  the  TI9900. 
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AH  soWware  a«x3ifob!<?  at  $if)gle-copy  pnces  o(  0£M/ 
Dealer  ogreemori!  pncos. 


MACRO-80  PACKAGE 

bier  now  has  o  complete  MACS 
IRPC.  CtPEAT.  local  vonabies  orxl 
condifiorxji  assernbty  hove  been  greatly 
plus  -ft«assernbler  IS  new  twice  os  tost 
The  MACPO-fiO  Pockoge,  including  Me 
ond  Ooss  Reference  Program,  moy  row  be  purchosed  sepor- 
otely  from  FOCTP/»N-80  Single  copy  S2C0  Manual  3i5  (MACR(> 
80  is  included  in  FORTPAN-8G.  Ver&on  3.1 ) 


one  company  sets  the  pace  with 
for  microprocessors. 

THATS  MICROSOFT. 


MBASIC  —  NEW  RELEASE  The  new  verson  5 OMSASC 
eludes  long  voncbie  names,  vanobie  length  records,  dynomc 
spoce  oitocoton.  WHLE/'/VENO.  protected  files,  and  choining  -with 
MON  verson 50  is  Wly  Af'ISl  compatibie  Our  MSASC documentafori hos 
beer,  complelety  lewnften  orxJ  is  signifoanlly  improied  Single  copy  5350 
Monual  $20 

EDIT-80  PACKAGE  (CP/M  version  only)  The fostesr  text  editor 

on  the  martlet  No  more  seorching  itvough  files  or  ayptc  commonds  'ms  rondom 
occess.  Iine  onented  editor  is  smniior  to  those  used  on  kyge  corrouters  fike  the  POP- 
10  Also  iroludes  FiCOM.  the  We  compare  uNity.  whch  oi'ows  cemponson  of  souce 
orxJ  btrory  files  Single  copy  S120  Monual  $10 


Whether  it’s  5ASC,  FCMPAN,  or 
COBOL,  the  largest-selling  mi¬ 
crocomputer  systems  use  soft- 
vyore  by  Microsoft 

Radio  Snack,  fekhonw.  NCR. 
Apote.  Commodore.  Cn- 
fei.  aiiings.  Extensys.  Im- 
soi  ChioScentific.  Cm 
memco,  />CCS  Z.Ioq 
Mostek.  Naticnai. 


Rockweii.  ond 
rnc-ny  oftiers 

And  C3t  Microsoft, 
new  things  ore 
hapf^enirvg  oli 
the  tim^s 


ANSI  74  COBOL-80.S  now  o.rt3!icc>le  with  fully  tested  iSAM,  imofoved  mteroctive 
/tCC£PT/l>SPlAY.  COPV  and  EXTEND  Single  copy  $750  Manual:  SX- 


PREVIEW  OF  UPCOMING  PRODUCTS  An  8oeo/z-8C  iyvsc  compiler  sup¬ 
porting  the  some  feolvjres  os  our  interpreter,  the  iong-o/.aited  8G80/Z-80  A\  interpre¬ 
ter.  ond  o  complete  set  of  systems  soffwore  products  tor  both  the  8086  oro  28000 


A  Microsoft  advertisement from  the 
January  1979  issue  of  Byte  magazine 
mentioning  some  products  and  the 
machines  they  ran  on.  In  the  lower 
right  corner  is  an  announcement  of 
the  company’s  move  to  Bellevue, 
Washington. 


During  this  same  period,  Marc  McDonald  also  worked  on  developing  an  8-bit  operating 
system  called  M-DOS  (usually  pronounced  “Midas”  or  “My  DOS”).  Although  it  never 
became  a  real  part  of  the  Microsoft  product  line,  M-DOS  was  a  true  multitasking  operating 
system  modeled  after  the  DEC  TOPS-10  operating  system.  M-DOS  provided  good  perfor¬ 
mance  and,  with  a  more  flexible  FAT  than  that  built  into  BASIC,  had  a  better  file-handling 
structure  than  the  up-and-coming  CP/M  operating  system.  At  about  30  KB,  however, 
M-DOS  was  unfortunately  too  big  for  an  8-bit  environment  and  so  ended  up  being  rele¬ 
gated  to  the  back  room.  As  Allen  describes  it,  “Trying  to  do  a  large,  full-blown  operating 
system  on  the  8080  was  a  lot  of  work,  and  it  took  a  lot  of  memory.  The  8080  addresses  only 
64  K,  so  with  the  success  of  CP/M,  we  finally  concluded  that  it  was  best  not  to  press  on 
with  that.” 

CP/M 

In  the  volatile  microcomputer  era  of  1976  through  1978,  both  users  and  developers  of  per¬ 
sonal  computers  quickly  came  to  recognize  the  limitations  of  running  applications  on  top 
of  Microsoft’s  Stand-alone  Disk  BASIC  or  any  other  language.  MITS,  for  example,  scheduled 
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a  July  1976  release  date  for  an  independent  operating  system  for  its  machine  that  used  the 
code  from  the  Altair’s  Disk  BASIC.  In  the  same  year,  Digital  Research,  headed  by  Gary 
Kildall,  released  its  Control  Program/Monitor,  or  CP/M. 

CP/M  was  a  typical  microcomputer  software  product  of  the  1970s  in  that  it  was  written  by 
one  person,  not  a  group,  in  response  to  a  specific  need  that  had  not  yet  been  filled.  One  of 
the  most  interesting  aspects  of  CP/M’s  history  is  that  the  software  was  developed  several 
years  before  its  release  date — actually,  several  years  before  the  hardware  on  which  it 
would  be  a  standard  became  commercially  available. 

In  1973,  Kildall,  a  professor  of  computer  science  at  the  Naval  Postgraduate  School  in 
Monterey,  California,  was  working  with  an  8080-based  small  computer  given  him  by  Intel 
Corporation  in  return  for  some  programming  he  had  done  for  the  company.  KildalPs 
machine,  equipped  with  a  monitor  and  paper-tape  reader,  was  certainly  advanced  for  the 
time,  but  Kildall  became  convinced  that  magnetic-disk  storage  would  make  the  machine 
even  more  efficient  than  it  was. 

Trading  some  programming  for  a  disk  drive  from  Shugart,  Kildall  first  attempted  to  build 
a  drive  controller  on  his  own.  Lacking  the  necessary  engineering  ability,  he  contacted  a 
friend,  John  Torode,  who  agreed  to  handle  the  hardware  aspects  of  interfacing  the  compu¬ 
ter  and  the  disk  drive  while  Kildall  worked  on  the  software  portion — the  refinement  of  an 
operating  system  he  had  written  earlier  that  year.  The  result  was  CP/M. 

The  version  of  CP/M  developed  by  Kildall  in  1973  underwent  several  refinements.  Kildall 
enhanced  the  CP/M  debugger  and  assembler,  added  a  BASIC  interpreter,  and  did  some 
work  on  an  editor,  eventually  developing  the  product  that,  from  about  1977  until  the  ap¬ 
pearance  of  the  IBM  Personal  Computer,  set  the  standard  for  8-bit  microcomputer  operat¬ 
ing  systems. 

Digital  Research’s  CP/M  included  a  command  interpreter  called  CCP  (Console  Command 
Processor),  which  acted  as  the  interface  between  the  user  and  the  operating  system  itself, 
and  an  operations  handler  called  BDOS  (Basic  Disk  Operating  System),  which  was 
responsible  for  file  storage,  directory  maintenance,  and  other  such  housekeeping  chores. 
For  actual  input  and  output — disk  I/O,  screen  display,  print  requests,  and  so  on — CP/M 
included  a  BIOS  (Basic  Input/Output  System)  tailored  to  the  requirements  of  the  hardware 
on  which  the  operating  system  ran. 

For  file  storage,  CP/M  used  a  system  of  eight-sector  allocation  units.  For  any  given  file,  the 
allocation  units  were  listed  in  a  directory  entry  that  included  the  filename  and  a  table  giv¬ 
ing  the  disk  locations  of  I6  allocation  units.  If  a  long  file  required  more  than  I6  allocation 
units,  CP/M  created  additional  directory  entries  as  required.  Small  files  could  be  accessed 
rapidly  under  this  system,  but  large  files  with  more  than  a  single  directory  entry  could  re¬ 
quire  numerous  relatively  time-consuming  disk  reads  to  find  needed  information. 

At  the  time,  however,  CP/M  was  highly  regarded  and  gained  the  support  of  a  broad  base  of 
hardware  and  software  developers  alike.  Quite  powerful  for  its  size  (about  4KB),  it  was,  in 
all  respects,  the  undisputed  standard  in  the  8-bit  world,  and  remained  so  until,  and  even 
after,  the  appearance  of  the  8086. 
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The  16-bit  Intel  8086  chip,  introduced  in  1978. 
Much  faster  and far  more  powerful  than  its  8-bit 
predecessor  the  8080,  the  8086 had  the  ability  to 
address  one  megabyte  of  memory. 


The  8086 

When  Intel  released  the  8-bit  8080  chip  in  1974,  the  Altair  was  still  a  year  in  the  future. 

The  8080  was  designed  not  to  make  computing  a  part  of  everyday  life  but  to  make  house¬ 
hold  appliances  and  industrial  machines  more  intelligent.  By  1978,  when  Intel  introduced 
the  l6-bit  8086,  the  microcomputer  was  a  reality  and  the  new  chip  represented  a  major 
step  ahead  in  performance  and  memory  capacity.  The  8086’s  full  l6-bit  buses  made  it  fast¬ 
er  than  the  8080,  and  its  ability  to  address  one  megabyte  of  random-access  memory  was  a 
giant  step  beyond  the  8080’s  64  KB  limit.  Although  the  8086  was  not  compatible  with  the 
8080,  it  was  architecturally  similar  to  its  predecessor  and  8080  source  code  could  be  me¬ 
chanically  translated  to  run  on  it.  This  translation  capability,  in  fact,  was  a  major  influence 
on  the  design  of  Tim  Paterson’s  operating  system  for  the  8086  and,  through  Paterson’s 
work,  on  the  first  released  version  of  MS-DOS. 

When  the  8086  arrived  on  the  scene,  Microsoft,  like  other  developers,  was  confronted  with 
two  choices:  continue  working  in  the  familiar  8-bit  world  or  turn  to  the  broader  horizons 
offered  by  the  new  l6-bit  technology.  For  a  time,  Microsoft  did  both.  Acting  on  Paul  Allen’s 
suggestion,  the  company  developed  the  SoftCard  for  the  popular  Apple  II,  which  was 
based  on  the  8-bit  6502  microprocessor.  The  SoftCard  included  a  Z80  microprocessor  and 
a  copy  of  CP/M-80  licensed  from  Digital  Research.  With  the  SoftCard,  Apple  II  users  could 
run  any  program  or  language  designed  to  run  on  a  CP/M  machine. 

It  was  l6-bit  technology,  however,  that  held  the  most  interest  for  Gates  and  Allen,  who 
believed  that  this  would  soon  become  the  standard  for  microcomputers.  Their  optimism 
was  not  universal  —  more  than  one  voice  in  the  trade  press  warned  that  industry  invest¬ 
ment  in  8-bit  equipment  and  software  was  too  great  to  successfully  introduce  a  new  stan¬ 
dard.  Microsoft,  however,  disregarded  these  forecasts  and  entered  the  l6-bit  arena  as  it 
had  with  the  Altair:  by  developing  a  stand-alone  version  of  BASIC  for  the  8086. 
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At  the  same  time  and,  coincidentally,  a  few  miles  south  in  Tukwila,  Washington,  a  major 
contribution  to  MS-DOS  was  taking  place.  Tim  Paterson,  working  at  Seattle  Computer 
Products,  a  company  that  built  memory  boards,  was  developing  an  8086  CPU  card  for  use 
in  an  S-100  bus  machine. 

86-DOS 

Paterson  was  introduced  to  the  8086  chip  at  a  seminar  held  by  Intel  in  June  1978.  He  had 
attended  the  seminar  at  the  suggestion  of  his  employer.  Rod  Brock  of  Seattle  Computer 
Products.  The  new  chip  sparked  his  interest  because,  as  he  recalls,  “all  its  instructions 
worked  on  both  8  and  16  bits,  and  you  didnt  have  to  do  everything  through  the  accumu¬ 
lator.  It  was  also  real  fast — it  could  do  a  l6-bit  ADD  in  three  clocks.” 

After  the  seminar,  Paterson — again  with  Brock’s  support — began  work  with  the  8086. 

He  finished  the  design  of  his  first  8086  CPU  board  in  January  1979  and  by  late  spring  had 
developed  a  working  CPU,  as  well  as  an  assembler  and  an  8086  monitor.  In  June,  Paterson 
took  his  system  to  Microsoft  to  try  it  with  Stand-alone  BASIC,  and  soon  after,  Microsoft 
BASIC  was  running  on  Seattle  Computer’s  new  board. 

During  this  period,  Paterson  also  received  a  call  from  Digital  Research  asking  whether 
they  could  borrow  the  new  board  for  developing  CP/M-86.  Though  Seattle  Computer  did 
not  have  a  board  to  loan,  Paterson  asked  when  CP/M-86  would  be  ready.  Digital’s  represen¬ 
tative  said  December  1979,  which  meant,  according  to  Paterson’s  diary,  “we’ll  have  to  live 
with  Stand-alone  BASIC  for  a  few  months  after  we  start  shipping  the  CPU,  but  then  we’ll  be 
able  to  switch  to  a  real  operating  system.” 

Early  in  June,  Microsoft  and  Tim  Paterson  attended  the  National  Computer  Conference 
in  New  York.  Microsoft  had  been  invited  to  share  Lifeboat  Associates’  ten-by-ten  foot 
booth,  and  Paterson  had  been  invited  by  Paul  Allen  to  show  BASIC  running  on  an  S-100 
8086  system.  At  that  meeting,  Paterson  was  introduced  to  Microsoft’s  M-DOS,  which  he 
found  interesting  because  it  used  a  system  for  keeping  track  of  disk  files — the  FAT  devel¬ 
oped  for  Stand-alone  BASIC — that  was  different  from  anything  he  had  encountered. 

After  this  meeting,  Paterson  continued  working  on  the  8086  board,  and  by  the  end  of  the 
year,  Seattle  Computer  Products  began  shipping  the  CPU  with  a  BASIC  option. 

When  CP/M-86  had  still  not  become  available  by  April  1980,  Seattle  Computer  Products 
decided  to  develop  a  l6-bit  operating  system  of  its  own.  Originally,  three  operating  sys¬ 
tems  were  planned:  a  single-user  system,  a  multiuser  version,  and  a  small  interim  product 
soon  informally  christened  QDOS  (for  Quick  and  Dirty  Operating  System)  by  Paterson. 

Both  Paterson  (working  on  QDOS)  and  Rod  Brock  knew  that  a  standard  operating  system 
for  the  8086  was  mandatory  if  users  were  to  be  assured  of  a  wide  range  of  application  soft¬ 
ware  and  languages.  CP/M  had  become  the  standard  for  8-bit  machines,  so  the  ability  to 
mechanically  translate  existing  CP/M  applications  to  run  on  a  l6-bit  system  became  one  of 
Paterson’s  major  goals  for  the  new  operating  system.  To  achieve  this  compatibility,  the  sys¬ 
tem  he  developed  mimicked  CP/M-80’s  functions  and  command  structure,  including  its 
use  of  file  control  blocks  (FCBs)  and  its  approach  to  executable  files. 
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G0 1 6-BIT  NOW  —  WE  HAVE  MADE  IT  EASY 


8086 

8  Mhz.  2-card  CPU  Set 

$ 


WITH  86-DOS^ 


595 


ASSEMBLED,  TESTED.  GUARANTEED 


With  our  2-carcj  8086  CPU  set  you  can  upgrade  your  Z80  8- 
bit  S-100  system  to  run  three  times  as  fast  by  swapping  the 
CPUs.  If  you  use  our  16-bit  memory,  it  will  run  live  times  as 
last.  Up  to  64K  ol  your  static  8-bit  memory  may  be  used  in  the 
8086  s  1  -megabyte  addressing  range.  A  switch  allows  either  4 
or  8  Mhz  operation  Memory  access  requirements  at  4  Mhz 
exceed  500  nsec. 

The  EPROM  monitor  allows  you  to  display,  alter,  and 
search  memory,  do  inputs  and  outputs,  and  boot  your  disk 
Debugging  aids  include  register  display  and  change,  single 
stepping,  and  execute  with  breakpoints 
The  set  includes  a  serial  pon  with  programmable  baud  rate, 
four  independent  programmable  16-bit  limers  (two  may  be 
combined  for  a  time-of-day  clock),  a  parallel  in  and  parallel  out 
port,  and  an  interrupt  controller  with  15  inputs  External  power 
may  be  applied  to  the  timers  to  maintain  the  clock  during 
system  power-off  time.  Total  power:  2  amps  at  +  8V.  less  than 
100  ma.  at  *  16V  and  at  -leV 
86-003".  our  S195  8086  single  user  disk  operating 
system,  is  provided  without  additional  charge  It  allows 
functions  such  as  console  I  O  of  characters  and  strings,  and 
random  or  sequencial  reading  and  writing  to  named  disk  files 
While  It  has  a  different  format  from  CP  M.  it  performs  similar 
calls  plus  some  extensions  (CP  M  is  a  registered  trademark  of 
Digital  Research  Corporation)  Its  construction  allows  relative¬ 
ly  easy  configuration  of  I  O  to  different  hardware  Directly 
supported  are  the  Tarbell  and  Cromemco  disk  controllers 
The  86-DOS"  package  includes  an  8086  resident  as¬ 
sembler.  a  Z80  to  8086  source  code  translator,  a  utility  to  read 
files  written  m  CP  M  and  convert  them  to  the  86-DOS  format,  a 
line  editor,  and  disk  maintenance  utilities  Of  significance  to 
Z80  users  is  the  ability  of  the  translator  to  accept  Z80  source 


code  written  for  CP  M,  translate  this  to  8086  source  code, 
assemble  the  source  code,  and  then  run  the  program  on  the 
8086  processor  under  86-DOS  This  allows  the  conversion  ol 
any  Z80  program,  for  which  source  code  is  available,  to  run  on 
the  much  higher  performance  8086 

BASIC-86  by  Microsoft  is  available  lor  the  8086  at  S350 
Several  firms  are  working  on  application  programs  Call  for 
current  software  status 

All  software  licensed  lor  use  on  a  single  computer  only 
Non-disdosure  agreements  required  Shipping  from  stock  to 
one  week  Bank  cards,  personal  checks,  CODs  okay  There  is 
a  l0-day  return  privilege  All  boards  are  guaranteed  one  year 
—  both  parts  and  labor  Shipped  prepaid  by  air  m  US  and 
Canada  Foreign  purchases  must  be  prepaid  m  US  funds 
Also  add  SlO  per  board  for  overseas  air  shipment 


8/16  16-BIT  MEMORY 

This  board  was  designed  for  the  1980s  It  is  configured  as 
16K  by  8  bits  when  accessed  by  an  8-bit  processor  and 
configured  8K  by  16  bits  when  used  with  a  16-bit  processor 
The  configuration  switching  is  automatic  and  is  done  by  the 
card  sampling  ihe  sixteen  request"  signal  sent  out  by  all  S- 
100  IEEE  16-bit  CPU  boards  The  card  has  all  the  high  noise 
immunity  features  of  our  well  known  PLUS  RAM  cards  as  well 
as  extended  addressing  Extended  addressing  is  a  replace¬ 
ment  tor  bank  select  It  makes  use  ol  a  total  of  24  address  lines 
to  givp  a  directly  addressable  range  of  over  16  megabytes 
(For  older  systems,  a  switch  will  cause  the  card  to  ignore  the 
top  8  address  lines  )  This  card  ensures  that  your  memory 
board  purchase  will  not  soon  be  obsolete  It  is  guaranteed  to 
run  without  wait  states  with  our  8086  CPU  set  using  an  8  Mhz 
clock  Shipped  from  stock  Prices  1-4.S280.5-9.S260  l0-up 
S240 


1  Seattle  Computer  Products,  Inc. 

1 1 1 4  Industry  Drive  SeaHlo  WA  98188 
1206)  575-1830 


An  advertisement  for 
the  Seattle  Computer 
Products  8086  CPU, 
with  86-DOS;  published 
in  the  December  1980 
issue  of  Byte. 


At  the  same  time,  however,  Paterson  was  dissatisfied  with  certain  elements  of  CP/M,  one 
of  them  being  its  file-allocation  system,  which  he  considered  inefficient  in  the  use  of  disk 
space  and  too  slow  in  operation.  So  for  fast,  efficient  file  handling,  he  used  a  file  allocation 
table,  as  Microsoft  had  done  with  Stand-alone  Disk  BASIC  and  M-DOS.  He  also  wrote  a 
translator  to  translate  8080  code  to  8086  code,  and  he  then  wrote  an  assembler  in  Z80 
assembly  language  and  used  the  translator  to  translate  it. 

Four  months  after  beginning  work,  Paterson  had  a  functioning  6  KB  operating  system, 
officially  renamed  86-DOS,  and  in  September  1980  he  contacted  Microsoft  again,  this  time 
to  ask  the  company  to  write  a  version  of  BASIC  to  run  on  his  system. 
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While  Paterson  was  developing  86-DOS,  the  third  major  element  leading  to  the  creation  of 
MS-DOS  was  gaining  force  at  the  opposite  end  of  the  country.  IBM,  until  then  seemingly 
oblivious  to  most  of  the  developments  in  the  microcomputer  world,  had  turned  its  atten¬ 
tion  to  the  possibility  of  developing  a  low-end  workstation  for  a  market  it  knew  well:  busi¬ 
ness  and  business  people. 

On  August  21, 1980,  a  study  group  of  IBM  representatives  from  Boca  Raton,  Florida,  visited 
Microsoft.  This  group,  headed  by  a  man  named  Jack  Sams,  told  Microsoft  of  IBM’s  interest 
in  developing  a  computer  based  on  a  microprocessor.  IBM  was,  however,  unsure  of  micro¬ 
computing  technology  and  the  microcomputing  market.  Traditionally,  IBM  relied  on  long 
development  cycles — typically  four  or  five  years — and  was  aware  that  such  lengthy 
design  periods  did  not  fit  the  rapidly  evolving  microcomputer  environment. 

One  of  IBM’s  solutions — the  one  outlined  by  Sams’s  group — was  to  base  the  new 
machine  on  products  from  other  manufacturers.  All  the  necessary  hardware  was  available, 
but  the  same  could  not  be  said  of  the  software.  Hence  the  visit  to  Microsoft  with  the  ques¬ 
tion:  Given  the  specifications  for  an  8-bit  computer,  could  Microsoft  write  a  ROM  BASIC  for 
it  by  the  following  April? 

Microsoft  responded  positively,  but  added  questions  of  its  own:  Why  introduce  an  8-bit 
computer?  Why  not  release  a  l6-bit  machine  based  on  Intel’s  8086  chip  instead?  At  the  end 
of  this  meeting — the  first  of  many — Sams  and  his  group  returned  to  Boca  Raton  with  a 
proposal  for  the  development  of  a  low-end,  l6-bit  business  workstation.  The  venture  was 
named  Project  Chess. 

One  month  later,  Sams  returned  to  Microsoft  asking  whether  Gates  and  Allen  could,  still 
by  April  1981,  provide  not  only  BASIC  but  also  FORTRAN,  Pascal,  and  COBOL  for  the  new 
computer.  This  time  the  answer  was  no  because,  though  Microsoft’s  BASIC  had  been 
designed  to  run  as  a  stand-alone  product,  it  was  unique  in  that  respect — the  other  lan¬ 
guages  would  need  an  operating  system.  Gates  suggested  CP/M-86,  which  was  then  still 
under  development  at  Digital  Research,  and  in  fact  made  the  initial  contact  for  IBM.  Digital 
Research  and  IBM  did  not  come  to  any  agreement,  however. 

Microsoft,  meanwhile,  still  wanted  to  write  all  the  languages  for  IBM — approximately  400 
KB  of  code.  But  to  do  this  within  the  allotted  six-month  schedule,  the  company  needed 
some  assurances  about  the  operating  system  IBM  was  going  to  use.  Further,  it  needed 
specific  information  on  the  internals  of  the  operating  system,  because  the  ROM  BASIC 
would  interact  intimately  with  the  BIOS. 

The  turning  point 

That  state  of  indecision,  then,  was  Microsoft’s  situation  on  Sunday,  September  28, 1980, 
when  Bill  Gates,  Paul  Allen,  and  Kay  Nishi,  a  Microsoft  vice  president  and  president  of 
ASCII  Corporation  in  Japan,  sat  in  Gates’s  eighth-floor  corner  office  in  the  Old  National 
Bank  Building  in  Bellevue,  Washington.  Gates  recalls,  “Kay  and  I  were  just  sitting  there  at 
night  and  Paul  was  on  the  couch.  Kay  said,  ‘Got  to  do  it,  got  to  do  it.’  It  was  only  20  more  K 
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of  code  at  most — actually,  it  turned  out  to  be  12  more  K  on  top  of  the  400.  It  wasn’t  that  big 
a  deal,  and  once  Kay  said  it,  it  was  obvious.  We’d  always  wanted  to  do  a  low-end  operating 
system,  we  had  specs  for  low-end  operating  systems,  and  we  knew  we  were  going  to  do 
one  up  on  l6-bit.” 

At  that  point.  Gates  and  Allen  began  looking  again  at  Microsoft’s  proposal  to  IBM.  Their 
estimated  400  KB  of  code  included  four  languages,  an  assembler,  and  a  linker.  To  add  an 
operating  system  would  require  only  another  20  KB  or  so,  and  they  already  knew  of  a 
working  model  for  the  8086:  Tim  Paterson’s  86-DOS.  The  more  Gates,  Allen,  and  Nishi 
talked  that  night  about  developing  an  operating  system  for  IBM’s  new  computer,  the  more 
possible — even  preferable — the  idea  became. 

Allen’s  first  step  was  to  contact  Rod  Brock  at  Seattle  Computer  Products  to  tell  him  that 
Microsoft  wanted  to  develop  and  market  SCP’s  operating  system  and  that  the  company  had 
an  OEM  customer  for  it.  Seattle  Computer  Products,  which  was  not  in  the  business  of 
marketing  software,  agreed  and  licensed  86-DOS  to  Microsoft.  Eventually,  SCP  sold  the 
operating  system  to  Microsoft  for  $50,000,  favorable  language  licenses,  and  a  license  back 
from  Microsoft  to  use  86-DOS  on  its  own  machines. 

In  October  1980,  with  86-DOS  in  hand,  Microsoft  submitted  another  proposal  to  IBM.  This 
time  the  plan  included  both  an  operating  system  and  the  languages  for  the  new  computer. 
Time  was  short  and  the  boundaries  between  the  languages  and  the  operating  system  were 
unclear,  so  Microsoft  explained  that  it  needed  to  control  the  development  of  the  operating 
system  in  order  to  guarantee  delivery  by  spring  of  1981.  In  November,  IBM  signed  the 
contract. 


Creating  MS-DOS 

At  Thanksgiving,  a  prototype  of  the  IBM  machine  arrived  at  Microsoft  and  Bill  Gates,  Paul 
Allen,  and,  primarily.  Bob  O’Rear  began  a  schedule  of  long,  sometimes  hectic  days  and 
total  immersion  in  the  project.  As  O’Rear  recalls,  “If  I  was  awake,  I  was  thinking  about 
the  project.” 

The  first  task  handled  by  the  team  was  bringing  up  86-DOS  on  the  new  machine.  This  was 
a  challenge  because  the  work  had  to  be  done  in  a  constantly  changing  hardware  environ¬ 
ment  while  changes  were  also  being  made  to  the  specifications  of  the  budding  operating 
system  itself. 

As  part  of  the  process,  86-DOS  had  to  be  compiled  and  integrated  with  the  BIOS,  which 
Microsoft  was  helping  IBM  to  write,  and  this  task  was  complicated  by  the  media.  Paterson’s 
86-DOS — not  counting  utilities  such  as  EDLIN,  CHKDSK,  and  INIT  (later  named 
FORMAT) — arrived  at  Microsoft  as  one  large  assembly-language  program  on  an  8-inch 
floppy  disk.  The  IBM  machine,  however,  used  SV^-inch  disks,  so  Microsoft  needed  to  de¬ 
termine  the  format  of  the  new  disk  and  then  find  a  way  to  get  the  operating  system  from 
the  old  format  to  the  new. 
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Paul  Allen  and 
Bill  Gates  (1982). 


This  work,  handled  by  O’Rear,  fell  into  a  series  of  steps.  First,  he  moved  a  section  of  code 
from  the  8-inch  disk  and  compiled  it.  Then,  he  converted  the  code  to  Intel  hexadecimal 
format.  Next,  he  uploaded  it  to  a  DEC-2020  and  from  there  downloaded  it  to  a  large  Intel 
fixed-disk  development  system  with  an  In-Circuit  Emulator.  The  DEC-2020  used  for  this 
task  was  also  used  in  developing  the  BIOS,  so  there  was  additional  work  in  downloading 
the  BIOS  to  the  Intel  machine,  converting  it  to  hexadecimal  format,  moving  it  to  an  IBM 
development  system,  and  then  crossloading  it  to  the  IBM  prototype. 

Defining  and  implementing  the  MS-DOS  disk  format — different  from  Paterson’s  8-inch 
format — was  an  added  challenge.  Paterson’s  ultimate  goal  for  86-DOS  was  logical  device 
independence,  but  during  this  first  stage  of  development,  the  operating  system  simply  had 
to  be  converted  to  handle  logical  records  that  were  independent  of  the  physical  record  size. 

Paterson,  still  with  Seattle  Computer  Products,  continued  to  work  on  86-DOS  and  by  the 
end  of  1980  had  improved  its  logical  device  independence  by  adding  functions  that 
streamlined  reading  and  writing  multiple  sectors  and  records,  as  well  as  records  of  variable 
size.  In  addition  to  making  such  refinements  of  his  own,  Paterson  also  worked  on  dozens 
of  changes  requested  by  Microsoft,  from  modifications  to  the  operating  system’s  startup 
messages  to  changes  in  EDLIN,  the  line  editor  he  had  written  for  his  own  use.  Throughout 
this  process,  IBM’s  security  restrictions  meant  that  Paterson  was  never  told  the  name  of  the 
OEM  and  never  shown  the  prototype  machines  until  he  left  Seattle  Computer  Products  and 
joined  Microsoft  in  May  1981. 

And  of  course,  throughout  the  process  the  developers  encountered  the  myriad  loose  ends, 
momentary  puzzles,  bugs,  and  unforeseen  details  without  which  no  project  is  complete. 
There  were,  for  example,  the  serial  card  interrupts  that  occurred  when  they  should  not 
and,  frustratingly,  a  hardware  constraint  that  the  BIOS  could  not  accommodate  at  first  and 
that  resulted  in  sporadic  crashes  during  early  MS-DOS  operations. 
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Bob  O’Rear's  sketch  of 
the  steps  involved  in 
moving  86-DOS  to  the 
IBM  prototype. 
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Part  of  Bob  OPear’s  “laundry”  list  of  operating-system  changes  and  corrections for  early  April  1981.  Around 
this  time,  interim  beta  copies  were  shipped  to  IBM  for  testing. 
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My  own  IBM  computer. 
Imagine  that.” 


Presenting  the  IBM  of 
Personal  Computers. 


‘Dad,  can  I  use 
the  IBM  computer 
tonight?” 


an  unusual  colorful  graphics,  your  son  or  daughter  will  discover 
omcnon.  It  what  makes  a  computer  tick — and  what  it  can  do.  They 
when  your  can  take  the  same  word  proccs.sing  program  you  u.se 

s<m  asks  to  to  create  business  reports  to  ^Tite  and  edit  txxvk  reports 

5  borrow  (and  learn  how  to  type  in  the  process)  Your  kids  might 
a  tie.  Or  even  get  so  'computer  smart.'  they’ll  start  writing 
when  your  their  tjwn  programs  in  BASIC  or  Pascal, 
daughter  Ultimately,  an  IB.M  Personal  Computer  can  be  one 

of  the  best  investments  you  make  in  your  familyS  future. 
And  one  of  the  lea.st  expensive.  Starting  at  less  than 
SI600'  thereH  a  system  that,  with  the  addition  of  one 
simple  device,  hooks  up  to  your  home  TV  and  uses  your 
audio  cas.sene  recorder. 

Tb  introduce  your  family  to  the  IB.M  Personal 
Computer,  visit  any'  ComputerLand*  store  or  .Sears 
Basiness  Systems  Center.  (>r  see  it  all  at  txx:  trf  our  IB.M 
Product  Centers.  (The  IB.M  National  Accounts  Division 
will  serve  business  customers  who  want  to  purchase  in 
quantity. ) 

Arxl  remember.  When  your  kids  ask  to  use  your 
IBM  Personal  Computer,  let  them.  But  just  make 
.  sure  you  c-an  get  it  back.  After  all  your  son’s 
L  still  wearing  that  tie.  s 


to  use  your  metal  racquet.  Sometimes  you  let  them.  Often 
you  don’t.  But  whrm  thcry  start  asking  to  use  yrxir  IBM 
Personal  Computer,  its  better  to  say  yes. 

Because  learning  abrxit  computers  is  a  subject  your 
kids  can  study  and  enjoy  at  home. 

Its  also  a  fact  that  the  IB.M  Personal  Computer  can 
be  as  useful  in  your  home  as  it  is  in  your  oflice.  To  help 
plan  the  family  budget,  for  iastance.  Or  to  compute 
anything  from  interest  paid  to  calories  consumed.  You 
can  even  up  directly  into  the  Dow  Jorves  dau  bank  with 
your  tcl<T>honc  and  an  inexpensive  adapter. 

But  as  surely  as  an  IBM  Personal  C’xxnputer 
can  help  you.  it  can  also  help  your  children. 

Because  ju.st  by  playing  games  or  drawing 


The  IBM  R^rscxial  Compute 


The  1981  debut  of  the 
IBM  Personal 
Computer. 


In  spite  of  such  difficulties,  however,  the  new  operating  system  ran  on  the  prototype  for 
the  first  time  in  February  1981.  In  the  six  months  that  followed,  the  system  was  continually 
refined  and  expanded,  and  by  the  time  of  its  debut  in  August  1981,  MS-DOS,  like  the  IBM 
Personal  Computer  on  which  it  appeared,  had  become  a  functional  product  for  home 
and  office  use. 
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Version  1 


The  first  release  of  MS-DOS,  version  1.0,  was  not  the  operating  system  Microsoft  envi¬ 
sioned  as  a  final  model  for  l6-bit  computer  systems.  According  to  Bill  Gates,  “Basically, 
what  we  wanted  to  do  was  one  that  was  more  like  MS-DOS  2,  with  the  hierarchical  file 
system  and  everything . . .  the  key  thing  [in  developing  version  1.0]  was  my  saying,  ‘Look, 
we  can  come  out  with  a  subset  first  and  just  go  upward  from  that.’” 

This  first  version — Gates’s  subset  of  MS-DOS — was  actually  a  good  compromise  be¬ 
tween  the  present  and  the  future  in  two  important  respects:  It  enabled  Microsoft  to  meet 
the  development  schedule  for  IBM  and  it  maintained  program-translation  compatibility 
with  CP/M. 

Available  only  for  the  IBM  Personal  Computer,  MS-DOS  1.0  consisted  of  4000  lines  of 
assembly-language  source  code  and  ran  in  8  KB  of  memory.  In  addition  to  utilities  such 
as  DEBUG,  EDLIN,  and  FORMAT,  it  was  organized  into  three  major  files.  One  file, 
IBMBIO.COM,  interfaced  with  the  ROM  BIOS  for  the  IBM  PC  and  contained  the  disk  and 
character  input/output  system.  A  second  file,  IBMDOS.COM,  contained  the  DOS  kernel,  in¬ 
cluding  the  application-program  interface  and  the  disk-file  and  memory  managers.  The 
third  file,  COMMAND.COM,  was  the  external  command  processor — the  part  of  MS-DOS 
most  visible  to  the  user. 

To  take  advantage  of  the  existing  base  of  languages  and  such  popular  applications  as 
WordStar  and  dBASE  II,  MS-DOS  was  designed  to  allow  software  developers  to  mechan¬ 
ically  translate  source  code  for  the  8080  to  run  on  the  8086.  And  because  of  this  link, 
MS-DOS  looked  and  acted  like  CP/M-80,  at  that  time  still  the  standard  among  operating 
systems  for  microcomputers.  Like  its  8-bit  relative,  MS-DOS  used  eight-character  filenames 
and  three-character  extensions,  and  it  had  the  same  conventions  for  identifying  disk  drives 
in  command  prompts.  For  the  most  part,  MS-DOS  also  used  the  same  command  language, 
offered  the  same  file  services,  and  had  the  same  general  structure  as  CP/M.  The  resem¬ 
blance  was  even  more  striking  at  the  programming  level,  with  an  almost  one-to-one  cor¬ 
respondence  between  CP/M  and  MS-DOS  in  the  system  calls  available  to  application 
programs. 


New  Features 

MS-DOS  was  not,  however,  a  CP/M  twin,  nor  had  Microsoft  designed  it  to  be  inextricably 
bonded  to  the  IBM  PC.  Hoping  to  create  a  product  that  would  be  successful  over  the  long 
term,  Microsoft  had  taken  steps  to  make  MS-DOS  flexible  enough  to  accommodate 
changes  and  new  directions  in  the  hardware  technology — disks,  memory  boards,  even 
microprocessors — on  which  it  depended.  The  first  steps  toward  this  independence  from 
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Big  I.B.M.’s  Little  Computer  Retail  Sales 

In  U.S.  Up 
1.3%  in  July 


BUSINESS 


Its  Desk-Top 
Model  Brings 
A  New  Image 


But  Analysts 
Are  Dubious  of 
General  Upturn 


IBM’s  New  Line  Likely  to  Shake  Up 
The  Market  for  Personal  Computers 


cairh  up  TTi^  fBM  machUi«  operate  on  an  far  greater,  wjulvalent  to  more  ttian  1.000 
Intel  Cnrp'  8008  mlrmpraresaor.  a  faster  typewritten  pages.  The  new  IBM  computers 
aril  more  nrwerfnl  "chip"  than  ihr.»  itwri  ilnn'i  iwe  all  that  capacity,  out  what  they  du 
In  rlvtb'  machines.  IBM  also  has  obtained  use  will  enaMe  them  toi  work  with  lonfer 
for  distribution  such  popular  program.^  as  programs  and  more  data  than  competing 
VlsiCalc.  a  flnanctal  forecasting  model  mar-  machines  and  to  display  Images  on  tbelr 
keted  by  Personal  Software  Inc.  vtdeo  screens  In  greater  detail 

Other  prvgrantf.  or  software,  for  the  But  the  added  memory  comes  at  a  price. 
IBM  etjulpmenl  tnctude  the  EasyWnter  IBM  acknowledges  that  a  fully  stocked  com- 
word-processing  system,  three  accounting  puter  will  cost  SS.OOO  or  more  Its  bask 
packages  from  Peachtree  Software  Inc.  and  11.50S  machine  comes  with  16.000  characters 


SEW  YORK-1"l*m«tlnn»l  Riulnewi  M* 
chines  Corp.  has  made  Its  bold  entry  Into 
the  personal-computer  market,  and  experts 
believe  the  computer  giani  could  capture  the 
lead  In  the  youthful  Industry  within  two 
years. 

Yesterday  the  company  tniroduced  sev¬ 
eral  versions  of  a  small  computer  designed 
lor  use  In  homes,  schools  and  offices.  Prices 


iWDfld 


uiaJyst  «l  Uor- 
'  nrw  system's 


IBM  AnnouncesNew  Microcomputer  System 

It’s  Official;  One  surprise  i _ _ ~ 

By  Thom  Hogan.  IW.SUiff  |  J 


IBM  really  gets  persor^al, 


Sears  and  Compulerland  computer  retail 
stores  as  well  as  directly  to  large  corporate 
and  educational  users.  IBM  says,  pointing 
out  that  it  has  set  up  a  special  national  mar¬ 
keting  team  to  handle  such  volume  orders. 

Donald  Estridge.  the  articulate  di¬ 
rector  of  IBM's  entry  systems  business  who 
braved  strobes  and  movie  lights  at  the  ma¬ 
chine's  Waldorf-Astoria  introduction,  de¬ 
clines  to  say  how  many  personnel  have  been 
dedicated  to  the  national  marketing  effort, 
but  says  it  will  be  selling  in  volumes  of  20 
machines  or  more.  Several  weeks  after  the 
unveiling,  he  said  response  so  far  had  been 
"very,  very  good."  with  orders  being  taken 
but  no  deliveries  to  be  made  before  this 
month. 

In  addition  to  the  game  of  Adven¬ 
ture.  which  Estridge  said  has  been  thor¬ 
oughly  exercised  by  his  Boca  Raton.  Fla., 
staff.  IBM  has  decked  out  the  machine  with 
an  array  of  packaged  applications  programs 
that  are  expected  to  m^e  it  attractive  to  the 
corporate  user. 

Among  these  are  the  popular  Visi- 
Calc  spreadsheet  package  from  Personal 
Software,  accounting  packages  from  Man¬ 
agement  Science  America's  Peachtree  Soft¬ 
ware  operation,  and  Information  Unlimit¬ 
ed's  EasyWriter  word  processing  system. 
Although  IBM  wouldn't  say,  more  indepen¬ 
dently  developed  packages  are  certain  to  be 
offered  for  the  computer  as  well  as  packages 


PERSONAL  COMPUTERS 


PERSONAL 
COMPUTER 
FROM  IBM 


The  mainframer’s  long- 
awaited  entry  into  the  personal 
computing  market  aims  for 
corporate  as  well  as  home 
users. 

With  uncharacteristic  but  resounding  fan¬ 
fare.  IBM  ended  the  summer's  most  popular 
guessing  game  for  the  industry  by  introduc¬ 
ing  its  Personal  Computer.  Highly  compa¬ 
rable  to  offerings  from  arch-contenders  Ap¬ 
ple  and  Radio  Shack,  the  machine  repre¬ 
sents  several  new  tacks  for  the  leading  com¬ 
puter  manufacturer  as  ii  attempts  to  hitch  its 
wagon  to  one  of  the  fastest  growing  seg¬ 
ments  of  the  industry. 

The  computer,  which  is  designed  to 
appeal  to  home  users  as  well  as  corporate 
professionals,  ranges  in  price  from  $I.S6S 
for  a  hare-bones  configuration  to  S6,300  for 
the  full-blown  model.  It  will  be  sold  through 


_ Jcntly  umrilcd  its  first  offering  in  the 

personal  computer  market — the  IBM  Personal 
Computer.  The  unit,  perhaps  surprisingly,  plays 
music  and  includes  game  software  to  sa>-  nothing 
of  the  standard  features  available. 

The  machine  is  impressive.  It^  starting  price  is  a 
mere  11565.  For  that  price  the  buyer  gets  the  83- 
key  keyboard,  the  computer  itself  based  on  an 
8088  microprocessor,  and  I6k  of  main  memory. 
This  minimal  configuration  can  use  a  tape  ca.s.scne 
for  mass  stor^c  and  a  television  set  (with  an  rf 


modulator )  for  a  display.  ( The  machine  is  fully  FCC 
certified  for  home  operation  as  a  class  B 
computing  device.) 

IBM  Ls  cognizant  of  the  fact  that  this  minimally 
configured  machine  probably  won't  last  a  .serious 
computerist  long  before  he  wants  to  expand.  The 
company  offers  upgraded  verskxis  of  the  machine, 
and  will  sell  them  in  different  configurations.  For 
example,  the  firm  lists  a  more  typical  txxtfif^iratkxi 
for  home  or  school  as  64k  of  main  memory,  one  disk 
continued  on  page  17 


FCrsorul  CIomputinR/ 


A  sampling  of  the  headlines  and  newspaper  articles  that  abounded  when  IBM  announced  its  Personal 
Computer. 
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MTCROSOFT 

QUARTERLY 


This  pokey  is  especially  advan¬ 
tageous  when  a  large  number  ol 
programs  is  distributed  using  a 
single  copy  ol  the  runtime  mod¬ 
ule  because  only  one  royalty 
payment  IS  paid 

( Miaosoft  stiH  supports  the 
runtime  system  us^  with  pre¬ 
vious  versions  It  application 
programmers  link  the  old  library 
to  their  appkcalions.  there  is 
no  royalty  lee.  This  applies  to 
versions  5  2  and  earker.  loo.) 

This  change  m  the 
BASCOM  royalty  pokey  reltecls 
Microsolt  s  wish  to  increase  the 
number  of  application  packages 
onthemarket  Thopokey 
change  the  addfwn  of  CHAIN 
with  COMMON,  and  the  im- 
plemeniaiion  of  the  runtime 
module  make  BASCOM  a  much 
more  flexibte  and  powerful  tool 
for  the  appkcatnn  programmer. 

BASCOM  5  3  IS  available 
now  lor  CP/M  systems, 
including  the  Apple  II  with  the 
Microsoft  Softcard.  MKrosofI 
IS  committed  to  supporting 
BASCOM  and  the  BASIC 
mierpreter  on  many  processors 
and  operating  systems,  thus 
assuring  that  application  pro¬ 
grams  aeated  with  BASCOM 
have,  arxl  will  continue  to  have, 
the  broadest  possible  market 


Paul  Allen 


IBM  Breaks  the 
16-Bit  Barrier 


The  most  important  feature  ol 
the  new  IBM  Personal  Compu¬ 
ter  is  its  8088  CPU  IBMschoice 
ol  the  8088  opens  up  two  areas 
ol  the  industry  that  have  been 


PMAMn  VetPrnOtn  ttciOMlI 


on  the  verge  of  changmg  lor 
the  past  to  rrxxiths:  first,  the 
industry  s  hesitancy  over  a 
senous  16-bit  software 
commitment  has  finatty  been 
broken;  and  second,  the 
capabilities  ol  the  t6-bit 
processors  are  finally  being 
put  to  some  really  exciting  uses 

A  16-bit  processor  gives 
software  designers  many 
advantages  inherent  in  an 
enhanced  instruction  set  For 
example,  we  ve  taken  advan¬ 
tage  ol  the  expanded  address¬ 
ing  in  our  MS-LINK,  a  linker  lor 
Pascal  or  FORTRAN  programs 
that  are  up  to  a  megabyte  in  size 
In  96K  ol  memory,  the  Microsolt 
8086  BASIC  interpreter  can 
execute  a  64K  program,  almost 
double  the  size  executable  on 
an  8-bit  hintime  Applications 
programs  can  be  more  sophis¬ 
ticated  in  their  features,  human 
engineenng  factors,  and  in 
solving  problems  that  involve 
larger  anxxjnts  ol  data . 

The  larger  number  of  reg¬ 
isters  with  the  8086/8088  pro¬ 
cessors  also  means  that  com¬ 


plex  operations,  such  as  floating 
point  and  graphics  routines 
execute  much  taster  The 
speed  ol  the  graphics  primitives 
in  MBASIC-86  makes  it  very 
easy  to  construct  a  graphics 
application  without  machine 
language. 

With  the  IBM  announcement 
ol  the  Personal  Computer,  it 
looks  as  though  the  industry  is 
finally  geanng  up  for  senous 
16-bit  soltwaie  support  In  addi¬ 
tion  to  the  Microsolt  software 
already  provided  lor  the  IBM 
Personal  Computer,  we  re 
planning  a  lul  kne  ol  t6-bit  lan¬ 
guages  and  erxl-user  software 
tools  Applicaiioo  packages  are 
rapkliy  being  adapted  to  the 
l6-bil  environment,  especially 
those  programs  already  written 
m  Microsolt  BASIC 

The  knch  pm  of  Microsoft  s 
new  t6-bit  product  kne  lor  the 
8086/8088  is  our  compact, 
flexible  operating  system.  MS- 
DOS  MS-DOS  IS  the  pnmary 
operating  system  on  the  IBM 
Personal  Computer  We  ve 
maintained  compatibikty  with 
existing  CP/M  2  x  operating 
system  cals,  so  it  s  a  straight¬ 
forward  process  to  convert  8080 
and  Z80  programs  to  am  imder 
MS-DOS  MS-DOS  also  pro¬ 
vides  a  future  upgrade  path 
to  the  XENIX  multi-user,  multi¬ 
tasking  environment.  Other 
important  features  of  MS-DOS 
include  enor  recovery,  device 
independent  I/O.  arxj  built-m 
vanabte  length  disk  reads  and 
water-  What  IS  now  the  stan¬ 
dard  operating  system  lor  the 
IBM  Personal  Computer  wiH 
no  doubt  become  an  industry 
standard. 

Now  that  the  16-bit  software 
barrier  has  been  crossed  and 
the  technical  capabilities  ol  the 
16-bit  processors  are  being 
appreaated.  Microsolt  expects 
to  see  many  16-bit  personal 
computers.  It's  an  industry  move 
we've  anticipated  lor  quite  some 
time  and.  given  the  momentum 
ol  IBM.  It  should  soon  be  m  full 
swing  _ 


Microsoft 
COBOL 
Passes  GSA 
Validation 


Microsoft  IS  always  con¬ 
cerned  about  standards  for  all 
ils  products  The  United  States 
government,  the  largest  user 
ol  computer  equipment  and 
software  in  the  world,  has  de¬ 
veloped  tests  lor  compkance 
with  and  implementation  ol 
standards  lor  compilers  Testing 
ol  compilers,  called  validation. 

IS  performed  by  government  in¬ 
spectors.  who  are  independent 
ol  software  developers 

Mcrosolt  submitted  its 
COBOL  compiler  (under  the 
CP/M  operating  system)  for 
validation  The  General 
Services  Admmislralion  (GSA) 
performed  the  validation  tests 
and  vakdated  Microsoft  COBOL 
as  a  tow-intemnediate  implemen¬ 
tation  ol  the  t974  ANSI  standard 
lor  COBOL 

Why  is  Microsolt  corx»med 
about  standards,  and  why  did 
we  submit  Microsolt  COBOL 
lor  validation'’  Mike  Orr.  COBOL 
product  manager,  ottered  the 
following  reasons 
(continued  on  back) 


A  page  frofn  Microsoft’s  third-quarter 
report  for  1981. 


specific  hardware  configurations  appeared  in  MS-DOS  version  1.0  in  the  form  of  device¬ 
independent  input  and  output,  variable  record  lengths,  relocatable  program  files,  and  a 
replaceable  command  processor. 

MS-DOS  made  input  and  output  device-independent  by  treating  peripheral  devices  as  if 
they  were  files.  To  do  this,  it  assigned  a  reserved  filename  to  each  of  the  three  devices  it 
recognized:  CON  for  the  console  (keyboard  and  display),  PRN  for  the  printer,  and  AUX  for 
the  auxiliary  serial  ports.  Whenever  one  of  these  reserved  names  appeared  in  the  file  con¬ 
trol  block  of  a  file  named  in  a  command,  all  operations  were  directed  to  the  device,  rather 
than  to  a  disk  file.  (A  file  control  block,  or  FCB,  is  a  37-byte  housekeeping  record  located 
in  an  application’s  portion  of  the  memory  space.  It  includes,  among  other  things,  the  file¬ 
name,  the  extension,  and  information  about  the  size  and  starting  location  of  the  file 
on  disk.) 

Such  device  independence  benefited  both  application  developers  and  computer  users. 

On  the  development  side,  it  meant  that  applications  could  use  one  set  of  read  and  write 
calls,  rather  than  a  number  of  different  calls  for  different  devices,  and  it  meant  that  an  ap¬ 
plication  did  not  have  to  be  modified  if  new  devices  were  added  to  the  system.  From  the 
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user’s  point  of  view,  device  independence  meant  greater  flexibility.  For  example,  even  if  a 
program  had  been  designed  for  disk  I/O  only,  the  user  could  still  use  a  file  for  input  or 
direct  output  to  the  printer. 

Variable  record  lengths  provided  another  step  toward  logical  independence.  In  CP/M,  logi¬ 
cal  and  physical  record  lengths  were  identical:  128  bytes.  Files  could  be  accessed  only  in 
units  of  128  bytes  and  file  sizes  were  always  maintained  in  multiples  of  128  bytes.  With 
MS-DOS,  however,  physical  sector  sizes  were  of  no  concern  to  the  user.  The  operating  sys¬ 
tem  maintained  file  lengths  to  the  exact  size  in  bytes  and  could  be  relied  on  to  support  logi¬ 
cal  records  of  any  size  desired. 

Another  new  feature  in  MS-DOS  was  the  relocatable  program  file.  Unlike  CP/M,  MS-DOS 
had  the  ability  to  load  two  different  types  of  program  files,  identified  by  the  extensions 
.COM  and  .EXE.  Program  files  ending  with  .COM  mimicked  the  binary  files  in  CP/M.  They 
were  more  compact  than  .EXE  files  and  loaded  somewhat  faster,  but  the  combined  pro¬ 
gram  code,  stack,  and  data  could  be  no  larger  than  64  KB.  A  .EXE  program,  on  the  other 
hand,  could  be  much  larger  because  the  file  could  contain  multiple  segments,  each  of 
which  could  be  up  to  64KB.  Once  the  segments  were  in  memory,  MS-DOS  then  used  part 
of  the  file  header,  the  relocation  table,  to  automatically  set  the  correct  addresses  for  each 
segment  reference. 

In  addition  to  supporting  .EXE  files,  MS-DOS  made  the  external  command  processor, 
COMMAND.COM,  more  adaptable  by  making  it  a  separate  relocatable  file  just  like  any 
other  program.  It  could  therefore  be  replaced  by  a  custom  command  processor,  as  long 
as  the  new  file  was  also  named  COMMAND.COM. 


Performance 

Everyone  familiar  with  the  IBM  PC  knows  that  MS-DOS  eventually  became  the  dominant 
operating  system  on  8086-based  microcomputers.  There  were  several  reasons  for  this,  not 
least  of  which  was  acceptance  of  MS-DOS  as  the  operating  system  for  IBM’s  phenomenally 
successful  line  of  personal  computers.  But  even  though  MS-DOS  was  the  only  operating 
system  available  when  the  first  IBM  PCs  were  shipped,  positioning  alone  would  not  neces¬ 
sarily  have  guaranteed  its  ability  to  outstrip  CP/M-86,  which  appeared  six  months  later. 
MS-DOS  also  offered  significant  advantages  to  the  user  in  a  number  of  areas,  including  the 
allocation  and  management  of  storage  space  on  disk. 

Like  CP/M,  MS-DOS  shared  out  disk  space  in  allocation  units.  Unlike  CP/M,  however, 
MS-DOS  mapped  the  use  of  these  allocation  units  in  a  central  file  allocation  table — the 
FAT — that  was  always  in  memory.  Both  operating  systems  used  a  directory  entry  for 
recording  information  about  each  file,  but  whereas  a  CP/M  directory  entry  included  an  al¬ 
location  map — a  list  of  sixteen  1  KB  allocation  units  where  successive  parts  of  the  file 
were  stored — an  MS-DOS  directory  entry  pointed  only  to  the  first  allocation  unit  in  the 
FAT  and  each  entry  in  the  table  then  pointed  to  the  next  unit  associated  with  the  file.  Thus, 
CP/M  might  require  several  directory  entries  (and  more  than  one  disk  access)  to  load  a  file 
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larger  than  16  KB,  but  MS-DOS  retained  a  complete  in-memory  list  of  all  file  components 
and  all  available  disk  space  without  having  to  access  the  disk  at  all.  As  a  result,  MS-DOS’s 
ability  to  find  and  load  even  very  long  files  was  extremely  rapid  compared  with  CP/M’s. 

Two  other  important  features — the  ability  to  read  and  write  multiple  records  with  one 
operating-system  call  and  the  transient  use  of  memory  by  the  MS-DOS  command 
processor — provided  further  efficiency  for  both  users  and  developers. 

The  independence  of  the  logical  record  from  the  physical  sector  laid  the  foundation  for  the 
ability  to  read  and  write  multiple  sectors.  When  reading  multiple  records  in  CP/M,  an  appli¬ 
cation  had  to  issue  a  read  function  call  for  each  sector,  one  at  a  time.  With  MS-DOS,  the  ap¬ 
plication  could  issue  one  read  function  call,  giving  the  operating  system  the  beginning 
record  and  the  number  of  records  to  read,  and  MS-DOS  would  then  load  all  of  the  corre¬ 
sponding  sectors  automatically. 

Another  innovative  feature  of  MS-DOS  version  1.0  was  the  division  of  the  command  pro¬ 
cessor,  COMMAND.COM,  into  a  resident  portion  and  a  transient  portion.  (There  is  also  a 
third  part,  an  initiali2ation  portion,  which  carries  out  the  commands  in  an  AUTOEXEC 
batch  file  at  startup.  This  part  of  COMMAND.COM  is  discarded  from  memory  when  its 
work  is  finished.)  The  reason  for  creating  resident  and  transient  portions  of  the  command 
processor  had  to  do  with  maximizing  the  efficiency  of  MS-DOS  for  the  user:  On  the  one 
hand,  the  programmers  wanted  COMMAND.COM  to  include  commonly  requested  func¬ 
tions,  such  as  DIR  and  COPY,  for  speed  and  ease  of  use;  on  the  other  hand,  adding  these 
commands  meant  increasing  the  size  of  the  command  processor,  with  a  resulting  decrease 
in  the  memory  available  to  application  programs.  The  solution  to  this  trade-off  of  speed 
versus  utility  was  to  include  the  extra  functions  in  a  transient  portion  of  COMMAND.COM 
that  could  be  overwritten  by  any  application  requiring  more  memory.  To  maintain  the  in¬ 
tegrity  of  the  functions  for  the  user,  the  resident  part  of  COMMAND.COM  was  given  the 
job  of  checking  the  transient  portion  for  damage  when  an  application  terminated.  If  neces¬ 
sary,  this  resident  portion  would  then  load  a  new  copy  of  its  transient  partner  into  memory. 


Ease  of  Use 

In  addition  to  its  moves  toward  hardware  independence  and  efficiency,  MS-DOS  included 
several  services  and  utilities  designed  to  make  life  easier  for  users  and  application  devel¬ 
opers.  Among  these  services  were  improved  error  handling,  automatic  logging  of  disks, 
date  and  time  stamping  of  files,  and  batch  processing. 

MS-DOS  and  the  IBM  PC  were  targeted  at  a  nontechnical  group  of  users,  and  from  the 
beginning  IBM  had  stressed  the  importance  of  data  integrity.  Because  data  is  most  likely 
to  be  lost  when  a  user  responds  incorrectly  to  an  error  message,  an  effort  was  made  to  in¬ 
clude  concise  yet  unambiguous  messages  in  MS-DOS.  To  further  reduce  the  risks  of  misin¬ 
terpretation,  Microsoft  used  these  messages  consistently  across  all  MS-DOS  functions  and 
utilities  and  encouraged  developers  to  use  the  same  messages,  where  appropriate,  in  their 
applications. 
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Instructions  for  Single  Disk  Drive  Users 

Two  pages  from  Microsoft’s  MS-DOS  version  1.0  manual.  On  the  left,  the  system ’s  requirements  —  8  KB  of 
memory;  on  the  right,  the  118-page  manual’s  complete  table  of  contents. 

In  a  further  attempt  to  safeguard  data,  MS-DOS  also  trapped  hard  errors — such  as  critical 
hardware  errors — that  had  previously  been  left  to  the  hardware-dependent  logic.  Now 
the  hardware  logic  could  simply  report  the  nature  of  the  error  and  the  operating  system 
would  handle  the  problem  in  a  consistent  and  systematic  way.  MS-DOS  could  also  trap  the 
Control-C  break  sequence  so  that  an  application  could  either  protect  against  accidental 
termination  by  the  user  or  provide  a  graceful  exit  when  appropriate. 

To  reduce  errors  and  simplify  use  of  the  system,  MS-DOS  also  automatically  updated  mem¬ 
ory  information  about  the  disk  when  it  was  changed.  In  CP/M,  users  had  to  log  new  disks 
as  they  changed  them — a  cumbersome  procedure  on  single-disk  systems  or  when  data 
was  stored  on  multiple  disks.  In  MS-DOS,  new  disks  were  automatically  logged  as  long  as 
no  file  was  currently  open. 

Another  new  feature — one  visible  with  the  DIR  command — was  date  and  time  stamping 
of  disk  files.  Even  in  its  earliest  forms,  MS-DOS  tracked  the  system  date  and  displayed  it  at 
every  startup,  and  now,  when  it  turned  out  that  only  the  first  l6  bytes  of  a  directory  entry 
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were  needed  for  file-header  information,  the  MS-DOS  programmers  decided  to  use  some 
of  the  remaining  l6  bytes  to  record  the  date  and  time  of  creation  or  update  (and  the  size  of 
the  file)  as  well. 

Batch  processing  was  originally  added  to  MS-DOS  to  help  IBM.  IBM  wanted  to  run 
scripts — sequences  of  commands  or  other  operations — one  after  the  other  to  test  various 
functions  of  the  system.  To  do  this,  the  testers  needed  an  automated  method  of  calling 
routines  sequentially.  The  result  was  the  batch  processor,  which  later  also  provided  users 
with  the  convenience  of  saving  and  running  MS-DOS  commands  as  batch  files. 

Finally,  MS-DOS  increased  the  options  available  to  a  program  when  it  terminated.  For  ex¬ 
ample,  in  less  sophisticated  operating  systems,  applications  and  other  programs  remained 
in  memory  only  as  long  as  they  were  active;  when  terminated,  they  were  removed  from 
memory.  MS-DOS,  however,  added  a  terminate-and-stay-resident  function  that  enabled  a 
program  to  be  locked  into  memory  and,  in  effect,  become  part  of  the  operating-system 
environment  until  the  computer  system  itself  was  shut  down  or  restarted. 


The  Marketplace 

When  IBM  announced  the  Personal  Computer,  it  said  that  the  new  machine  would  run 
three  operating  systems:  MS-DOS,  CP/M-86,  and  Sof  Tech  Microsystem’s  p-System.  Of  the 
three,  only  MS-DOS  was  available  when  the  IBM  PC  shipped.  Nevertheless,  when  MS-DOS 
was  released,  nine  out  of  ten  programs  on  the  InfoWorld  bestseller  list  for  1981  ran  under 
CP/M-80,  and  CP/M-86,  which  became  available  about  six  months  later,  was  the  operating 
system  of  choice  to  most  writers  and  reviewers  in  the  trade  press. 

Understandably,  MS-DOS  was  compared  with  CP/M-80  and,  later,  CP/M-86.  The  main  con¬ 
cern  was  compatibility:  To  what  extent  was  Microsoft’s  new  operating  system  compatible 
with  the  existing  st.andard?  No  one  could  have  foreseen  that  MS-DOS  would  not  only  catch 
up  with  but  supersede  CP/M.  Even  Bill  Gates  now  recalls  that  “our  most  optimistic  view  of 
the  number  of  machines  using  MS-DOS  wouldn’t  have  matched  what  really  ended  up 
happening.” 

To  begin  with,  the  success  of  the  IBM  PC  itself  surprised  many  industry  watchers.  Within  a 
year,  IBM  was  selling  30,000  PCs  per  month,  thanks  in  large  part  to  a  business  community 
that  was  already  comfortable  with  IBM’s  name  and  reputation  and,  at  least  in  retrospect, 
was  ready  for  the  leap  to  personal  computing.  MS-DOS,  of  course,  benefited  enormously 
from  the  success  of  the  IBM  PC — in  large  part  because  IBM  supplied  all  its  languages  and 
applications  in  MS-DOS  format. 

But,  at  first,  writers  in  the  trade  press  still  believed  in  CP/M  and  questioned  the  viability  of 
a  new  operating  system  in  a  world  dominated  by  CP/M-80.  Many  assumed,  incorrectly,  that 
a  CP/M-86  machine  could  run  CP/M-80  applications.  Even  before  CP/M-86  was  available. 
Future  Computing  referred  to  the  IBM  PC  as  the  “CP/M  Record  Player” — presumably  in 
anticipation  of  a  vast  inventory  of  CP/M  applications  for  the  new  computer — and  led  its 
readers  to  assume  that  the  PC  was  actually  a  CP/M  machine. 
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Microsoft,  meanwhile,  held  to  the  belief  that  the  success  of  IBM’s  machine  or  any  other 
l6-bit  microcomputer  depended  ultimately  on  the  emergence  of  an  industry  standard  for  a 
l6-bit  operating  system.  Software  developers  could  not  afford  to  develop  software  for  even 
two  or  three  different  operating  systems,  and  users  could  (or  would)  not  pay  the  prices  the 
developers  would  have  to  charge  if  they  did.  Furthermore,  users  would  almost  certainly 
rebel  against  the  inconvenience  of  sharing  data  stored  imder  different  operating-system 
formats.  There  had  to  be  one  operating  system,  and  Microsoft  wanted  MS-DOS  to  be 
the  one. 

The  company  had  already  taken  the  first  step  toward  a  standard  by  choosing  hardware 
independent  designs  wherever  possible.  Machine  independence  meant  portability,  and 
portability  meant  that  Microsoft  could  sell  one  version  of  MS-DOS  to  different  hardware 
manufacturers  who,  in  turn,  could  adapt  it  to  their  own  equipment.  Portability  alone, 
however,  was  no  guarantee  of  industry-wide  acceptance.  To  make  MS-DOS  the  standard, 
Microsoft  needed  to  convince  software  developers  to  write  programs  for  MS-DOS.  And  in 
1981,  these  developers  were  a  little  confused  about  IBM’s  new  operating  system. 

An  operating  system  by  any  other  name . . . 

A  tangle  of  names  gave  rise  to  one  point  of  confusion  about  MS-DOS.  Tim  Paterson’s 
“Quick  and  Dirty  Operating  System”  for  the  8086  was  originally  shipped  by  Seattle 
Computer  Products  as  86-DOS.  After  Microsoft  purchased  86-DOS,  the  name  remained 
for  a  while,  but  by  the  time  the  PC  was  ready  for  release,  the  new  system  was  known  as 
MS-DOS.  Then,  after  the  IBM  PC  reached  the  market,  IBM  began  to  refer  to  the  operating 
system  as  the  IBM  Personal  Computer  DOS,  which  the  trade  press  soon  shortened  to 
PC-DOS.  IBM’s  version  contained  some  utilities,  such  as  DISKCOPY  and  DISKCOMP,  that 
were  not  included  in  MS-DOS,  the  generic  version  available  for  license  by  other  mantofac- 
turers.  By  calling  attention  to  these  differences,  publications  added  to  the  confusion  about 
the  distinction  between  the  Microsoft  and  IBM  releases  of  MS-DOS. 

Further  complications  arose  when  Lifeboat  Associates  agreed  to  help  promote  MS-DOS  but 
decided  to  call  the  operating  system  Software  Bus  86.  MS-DOS  thus  became  one  of  a  line 
of  trademarked  Software  Bus  products,  another  of  which  was  a  product  called  SB-80, 
Lifeboat’s  version  of  CP/M-80. 

Finally,  some  of  the  first  hardware  companies  to  license  MS-DOS  also  wanted  to  use  their 
own  names  for  the  operating  system.  Out  of  this  situation  came  such  additional  names  as 
COMPAQ-DOS  and  Zenith’s  Z-DOS. 

Given  this  confusing  host  of  names  for  a  product  it  believed  could  become  the  industry 
standard,  Microsoft  finally  took  the  lead  and,  as  developer,  insisted  that  the  operating  sys¬ 
tem  was  to  be  called  MS-DOS.  Eventually,  everyone  but  IBM  complied. 

Developers  and  MS-DOS 

Early  in  its  career,  MS-DOS  represented  just  a  small  fraction  of  Microsoft’s  business — 
much  larger  revenues  were  generated  by  BASIC  and  other  languages.  In  addition,  in  the 
first  two  years  after  the  introduction  of  the  IBM  PC,  the  growth  of  CP/M-86  and  other 
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environments  nearly  paralleled  that  of  MS-DOS.  So  Microsoft  found  itself  in  the  unenviable 
position  of  giving  its  support  to  MS-DOS  while  also  selling  languages  to  run  on  CP/M-86, 
thereby  contributing  to  the  growth  of  software  for  MS-DOS’s  biggest  competitor. 

Given  the  uncertain  outcome  of  this  two-horse  race,  some  other  software  developers 
chose  to  wait  and  see  which  way  the  hardware  manufacturers  would  jump.  For  their  part, 
the  hardware  manufacturers  were  confronting  the  issue  of  compatibility  between  operat¬ 
ing  systems.  Specifically,  they  needed  to  be  convinced  that  MS-DOS  was  not  a  maverick — 
that  it  could  perform  as  well  as  CP/M-86  as  a  base  for  applications  that  had  been  ported 
from  the  CP/M-80  environment  for  use  on  l6-bit  computers. 

Microsoft  approached  the  problem  by  emphasizing  four  related  points  in  its  discussions 
with  hardware  manufacturers: 

•  First,  one  of  Microsoft’s  goals  in  developing  the  first  version  of  MS-DOS  had  always 
been  translation  compatibility  from  CP/M-80  to  MS-DOS  software. 

•  Second,  translation  was  possible  only  for  software  written  in  8080  or  Z80  assembly 
language;  thus,  neither  MS-DOS  nor  CP/M-86  could  run  programs  written  for  other 
8-bit  processors,  such  as  the  6800  or  the  6502. 

•  Third,  many  applications  were  written  in  a  high-level  language,  rather  than  in  assem¬ 
bly  language. 

•  Fourth,  most  of  those  high-level  languages  were  Microsoft  products  and  ran  on 
MS-DOS. 

Thus,  even  though  some  people  had  originally  believed  that  only  CP/M-86  would  auto¬ 
matically  make  the  installed  base  of  CP/M-80  software  available  to  the  IBM  PC  and  other 
l6-bit  computers,  Microsoft  convinced  the  hardware  manufacturers  that  MS-DOS  was,  in 
actuality,  as  flexible  as  CP/M-86  in  its  compatibility  with  existing — and  appropriate — 
CP/M-80  software. 

MS-DOS  was  put  at  a  disadvantage  in  one  area,  however,  when  Digital  Research  convinced 
several  manufacturers  to  include  both  8080  and  8086  chips  in  their  machines.  With  8-bit 
and  l6-bit  software  used  on  the  same  machine,  the  user  could  rely  on  the  same  disk  format 
for  both  types  of  software.  Because  MS-DOS  used  a  different  disk  format,  CP/M  had  the 
edge  in  these  dual-processor  machines — although,  in  fact,  it  did  not  seem  to  have  much 
effect  on  the  survival  of  CP/M-86  after  the  first  year  or  so. 

Although  making  MS-DOS  the  operating  system  of  obvious  preference  was  not  as  easy  as 
simply  convincing  hardware  manufacturers  to  offer  it,  Microsoft’s  list  of  MS-DOS  custom¬ 
ers  grew  steadily  from  the  time  the  operating  system  was  introduced.  Many  manufacturers 
continued  to  offer  CP/M-86  along  with  MS-DOS,  but  by  the  end  of  1983  the  technical  supe¬ 
riority  of  MS-DOS  (bolstered  by  the  introduction  of  such  products  as  Lotus  1-2-3)  carried 
the  market.  For  example,  when  DEC,  a  longtime  holdout,  decided  to  make  MS-DOS  the  pri¬ 
mary  operating  system  for  its  Rainbow  computer,  the  company  mentioned  the  richer  set  of 
commands  and  “dramatically”  better  disk  performance  of  MS-DOS  as  reasons  for  its 
choice  over  CP/M-86. 
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A  Microsoft  original  equipment  manufacturer  (OEM)  marketing  brochure  describing  the  strengths  of  MS-DOS. 
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Version  2 


After  the  release  of  PC-specific  version  1.0  of  MS-DOS,  Microsoft  worked  on  an  update 
that  contained  some  bug  fixes.  Version  1.1  was  provided  to  IBM  to  run  on  the  upgraded  PC 
released  in  1982  and  enabled  MS-DOS  to  work  with  double-sided,  320  KB  floppy  disks. 
This  version,  referred  to  as  1.25  by  all  but  IBM,  was  the  first  version  of  MS-DOS  shipped  by 
other  OEMs,  including  COMPAQ  and  Zenith. 

Even  before  these  intermediate  releases  were  available,  however,  Microsoft  began  plan¬ 
ning  for  future  versions  of  MS-DOS.  In  developing  the  first  version,  the  programmers  had 
had  two  primary  goals:  running  translated  CP/M-80  software  and  keeping  MS-DOS  small. 
They  had  neither  the  time  nor  the  room  to  include  more  sophisticated  features,  such  as 
those  typical  of  Microsoft’s  UNIX-based  multiuser,  multitasking  operating  system,  XENIX. 
But  when  IBM  informed  Microsoft  that  the  next  major  edition  of  the  PC  would  be  the 
Personal  Computer  XT  with  a  10-megabyte  fixed  disk,  a  larger,  more  powerful  version  of 
MS-DOS — one  closer  to  the  operating  system  Microsoft  had  envisioned  from  the  start — 
became  feasible. 

There  were  three  particular  areas  that  interested  Microsoft:  a  new,  hierarchical  file  system, 
installable  device  drivers,  and  some  type  of  multitasking.  Each  of  these  features  contrib¬ 
uted  to  version  2.0,  and  together  they  represented  a  major  change  in  MS-DOS  while  still 
maintaining  compatibility  with  version  1.0. 


The  File  System 

Primary  responsibility  for  version  2.0  fell  to  Paul  Allen,  Mark  Zbikowski,  and  Aaron 
Reynolds,  who  wrote  (and  rewrote)  most  of  the  version  2.0  code.  The  major  design  issue 
confronting  the  developers,  as  well  as  the  most  visible  example  of  its  difference  from  ver¬ 
sions  1.0, 1.1,  and  1.25,  was  the  introduction  of  a  hierarchical  file  system  to  handle  the  file- 
management  needs  of  the  XT’s  fixed  disk. 

Version  1.0  had  a  single  directory  for  all  the  files  on  a  floppy  disk.  That  system  worked  well 
enough  on  a  disk  of  limited  capacity,  but  on  a  10-megabyte  fixed  disk  a  single  directory 
could  easily  become  unmanageably  large  and  cumbersome. 

CP/M  had  approached  the  problem  of  high-capacity  storage  media  by  using  a  partitioning 
scheme  that  divided  the  fixed  disk  into  10  user  areas  equivalent  to  10  separate  floppy-disk 
drives.  On  the  other  hand,  UNIX,  which  had  traditionally  dealt  with  larger  systems,  used 
a  branching,  hierarchical  file  structure  in  which  the  user  could  create  directories  and 
subdirectories  to  organize  files  and  make  them  readily  accessible.  This  was  the  file- 
management  system  implemented  in  XENIX,  and  it  was  the  MS-DOS  team’s  choice  for 
handling  files  on  the  XT’s  fixed  disk. 
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The  MS-DOS  version  1.0  manual  next  to  the  version  2.0  manual. 


Partitioning,  IBM’s  initial  choice,  had  the  advantages  of  familiarity,  size,  and  ease  of  imple¬ 
mentation.  Many  small-system  users  —  particularly  software  developers — were  already 
familiar  with  partitioning,  if  not  overly  fond  of  it,  from  their  experience  with  CP/M.  Devel¬ 
opment  time  was  also  a  major  concern,  and  the  code  needed  to  develop  a  partitioning 
scheme  would  be  minimal  compared  with  the  code  required  to  manage  a  hierarchical  file 
system.  Such  a  scheme  would  also  take  less  time  to  implement. 

However,  partitioning  had  two  inherent  disadvantages.  First,  its  functionality  would 
decrease  as  storage  capacity  increased,  and  even  in  1982,  Microsoft  was  anticipating  sub¬ 
stantial  growth  in  the  storage  capacity  of  disk-based  media.  Second,  partitioning  de¬ 
pended  on  the  physical  device.  If  the  size  of  the  disk  changed,  either  the  number  or  the 
size  of  the  partitions  must  also  be  changed  in  the  code  for  both  the  operating  system  and 
the  application  programs.  For  Microsoft,  with  its  commitment  to  hardware  independence, 
partitioning  would  have  represented  a  step  in  the  wrong  direction. 

A  hierarchical  file  structure,  on  the  other  hand,  could  be  independent  of  the  physical 
device.  A  disk  could  be  partitioned  logically,  rather  than  physically.  And  because  these 
partitions  (directories)  were  controlled  by  the  user,  they  were  open-ended  and  enabled 
the  individual  to  determine  the  best  way  of  organizing  a  disk. 

Ultimately,  it  was  a  hierarchical  file  system  that  found  its  way  into  MS-DOS  2.0  and  even¬ 
tually  convinced  everyone  that  it  was,  indeed,  the  better  and  more  flexible  solution  to  the 
problem  of  supporting  a  fixed  disk.  The  file  system  was  logically  consistent  with  the 
XENIX  file  structure,  yet  physically  consistent  with  the  file  access  incorporated  in  versions 
1.x,  and  was  based  on  a  root,  or  main,  directory  under  which  the  user  could  create  a  sys¬ 
tem  of  subdirectories  and  sub-subdirectories  to  hold  files.  Each  file  in  the  system  was  iden¬ 
tified  by  the  directory  path  leading  to  it,  and  the  number  of  subdirectories  was  limited  only 
by  the  length  of  the  pathname,  which  could  not  exceed  64  characters. 

In  this  file  structure,  all  the  subdirectories  and  the  filename  in  a  path  were  separated 
from  one  another  by  backslash  characters,  which  represented  the  only  anomaly  in  the 
XENIX/MS-DOS  system  of  hierarchical  files.  XENIX  used  a  forward  slash  as  a  separator, 
but  versions  1.x  of  MS-DOS,  borrowing  from  the  tradition  of  DEC  operating  systems, 
already  used  the  forward  slash  for  switches  in  the  command  line,  so  Microsoft,  at  IBM’s 
request,  decided  to  use  the  backslash  as  the  separator  instead.  Although  the  backslash 
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character  created  no  practical  problems,  except  on  keyboards  that  lacked  a  backslash,  this 
decision  did  introduce  inconsistency  between  MS-DOS  and  existing  UNIX-like  operating 
systems.  And  although  Microsoft  solved  the  keyboard  problem  by  enabling  the  user  to 
change  the  switch  character  from  a  slash  to  a  hyphen,  the  solution  itself  created  compati¬ 
bility  problems  for  people  who  wished  to  exchange  batch  files. 

Another  major  change  in  the  file-management  system  was  related  to  the  new  directory 
structure:  In  order  to  fully  exploit  a  hierarchical  file  system,  Microsoft  had  to  add  a  new 
way  of  calling  file  services. 

Versions  1.x  of  MS-DOS  used  CP/M-like  structures  called  file  control  blocks,  or  FCBs,  to 
maintain  compatibility  with  older  CP/M-80  programs.  The  FCBs  contained  all  pertinent 
information  about  the  size  and  location  of  a  file  but  did  not  allow  the  user  to  specify  a  file 
in  a  different  directory.  Therefore,  version  2.0  of  MS-DOS  needed  the  added  ability  to  ac¬ 
cess  files  by  means  of  handles,  or  descriptors,  that  could  operate  across  directory  lines. 

In  this  added  step  toward  logical  device  independence,  MS-DOS  returned  a  handle  when¬ 
ever  an  MS-DOS  program  opened  a  file.  All  further  interaction  with  the  file  involved  only 
this  handle.  MS-DOS  made  all  necessary  adjustments  to  an  internal  structure — different 
from  an  FCB — so  that  the  program  never  had  to  deal  directly  with  information  about  the 
file’s  location  in  memory.  Furthermore,  even  if  future  versions  of  MS-DOS  were  to  change 
the  structure  of  the  internal  control  units,  program  code  would  not  need  to  be  rewritten — 
the  file  handle  would  be  the  only  referent  needed,  and  this  would  not  change. 

Putting  the  internal  control  units  under  the  supervision  of  MS-DOS  and  substituting 
handles  for  FCBs  also  made  it  possible  for  MS-DOS  to  redirect  a  program’s  input  and  out¬ 
put.  A  system  function  was  provided  that  enabled  MS-DOS  to  divert  the  reads  or  writes 
directed  to  one  handle  to  the  file  or  device  assigned  to  another  handle.  This  capability  was 
used  by  COMMAND.COM  to  allow  output  from  a  file  to  be  redirected  to  a  device,  such  as  a 
printer,  or  to  be  piped  to  another  program.  It  also  allowed  system  cleanup  on  program 
terminations. 


Installable  Device  Drivers 

At  the  time  Microsoft  began  developing  version  2.0  of  MS-DOS,  the  company  also  realized 
that  many  third-party  peripheral  devices  were  not  working  well  with  one  another.  Each 
manufacturer  had  its  own  way  of  hooking  its  hardware  into  MS-DOS  and  if  two  third-party 
devices  were  plugged  into  a  computer  at  the  same  time,  they  would  often  conflict  or  fail. 

One  of  the  hallmarks  of  IBM’s  approach  to  the  PC  was  open  architecture,  meaning  that 
users  could  simply  slide  new  cards  into  the  computer  whenever  new  input/output  de¬ 
vices,  such  as  fixed  disks  or  printers,  were  added  to  the  system.  Unfortunately,  version 
1.0  of  MS-DOS  did  not  have  a  corresponding  open  architecture  built  into  it — the  BIOS 
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contained  all  the  code  that  permitted  the  operating  system  to  run  the  hardware.  If  inde¬ 
pendent  hardware  manufacturers  wanted  to  develop  equipment  for  use  with  a  computer 
manufacturer’s  operating  system,  they  would  have  to  either  completely  rewrite  the  device 
drivers  or  write  a  complicated  utility  to  read  the  existing  drivers,  alter  them,  add  the  code 
to  support  the  new  device,  and  produce  a  working  set  of  drivers.  If  the  user  installed  more 
than  one  device,  these  patches  would  often  conflict  with  one  another.  Furthermore,  they 
would  have  to  be  revised  each  time  the  computer  manufacturer  updated  its  version 
of  MS-DOS. 

By  the  time  work  began  on  version  2.0,  the  MS-DOS  team  knew  that  the  ability  to  install 
any  device  driver  at  run  time  was  vital.  They  implemented  installable  device  drivers  by 
making  the  drivers  more  modular.  Like  the  FAT,  lO.SYS  (IBMBIO.COM  in  PC-DOS) 
became,  in  effect,  a  linked  list — this  time,  of  device  drivers — that  could  be  expanded 
through  commands  in  the  CONFIG.SYS  file  on  the  system  boot  disk.  Manufacturers  could 
now  write  a  device  driver  that  the  user  could  install  at  run  time  by  including  it  in  the 
CONFIG.SYS  file.  MS-DOS  could  then  add  the  device  driver  to  the  linked  list. 

By  extension,  this  ability  to  install  device  drivers  also  added  the  ability  to  supersede  a  pre¬ 
viously  installed  driver — for  example,  the  ANSI.SYS  console  driver  that  supports  the  ANSI 
standard  escape  codes  for  cursor  positioning  and  screen  control. 


Print  Spooling 

At  IBM’s  request,  version  2.0  of  MS-DOS  also  possessed  the  undocumented  ability  to  per¬ 
form  rudimentary  background  processing — an  interim  solution  to  a  growing  awareness  of 
the  potentials  of  multitasking. 

Background  print  spooling  was  sufficient  to  meet  the  needs  of  most  people  in  most  situa¬ 
tions,  so  the  print  spooler,  PRINT.COM,  was  designed  to  run  whenever  MS-DOS  had 
nothing  else  to  do.  When  the  parent  application  became  active,  PRINT.COM  would  be  in¬ 
terrupted  until  the  next  lull.  This  type  of  background  processing,  though  both  limited  and 
extremely  complex,  was  exploited  by  a  number  of  applications,  such  as  SideKick. 


Loose  Ends  and  a  New  MS-DOS 

Hierarchical  files,  installable  device  drivers,  arid  print  spooling  were  the  major  design 
decisions  in  version  2.0.  But  there  were  dozens  of  smaller  changes,  too. 

For  example,  with  the  fixed  disk  it  was  necessary  to  modify  the  code  for  automatic  logging 
of  disks.  This  modification  meant  that  MS-DOS  had  to  access  the  disk  more  often,  and  file 
access  became  much  slower  as  a  result.  In  trying  to  find  a  solution  to  this  problem,  Chris 
Peters  reasoned  that,  if  MS-DOS  had  just  checked  the  disk,  there  was  some  minimum  time 
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Two  members  of  the 
IBM  line  of  personal 
computers  for  which 
versions  1  and  2  of 
MS-DOS  were  devel¬ 
oped.  On  the  left,  the 
original  IBM  PC  (ver¬ 
sion  1.0  of  MS-DOS); 
on  the  right,  the  IBM 
PC/XT  ( version  2. 0). 


a  user  would  need  to  physically  change  disks.  If  that  minimum  time  had  not  elapsed,  the 
current  disk  information  in  RAM — whether  for  a  fixed  disk  or  a  floppy — was  probably 
still  good. 

Peters  found  that  the  fastest  anyone  could  physically  change  disks,  even  if  the  disks  were 
damaged  in  the  process,  was  about  two  seconds.  Reasoning  from  this  observation,  he  had 
MS-DOS  check  to  see  how  much  time  had  gone  by  since  the  last  disk  access.  If  less  than 
two  seconds  had  elapsed,  he  had  MS-DOS  assume  that  a  new  disk  had  not  been  inserted 
and  that  the  disk  information  in  RAM  was  still  valid.  With  this  little  trick,  the  speed  of  file 
handling  in  MS-DOS  version  2.0  increased  considerably. 

Version  2.0  was  released  in  March  1983,  the  product  of  a  surprisingly  small  team  of  six  de¬ 
velopers,  including  Peters,  Mani  Ulloa,  and  Nancy  Panners  in  addition  to  Allen,  Zbikowski, 
and  Reynolds.  Despite  its  complex  new  features,  version  2.0  was  only  24  KB  of  code. 
Though  it  maintained  its  compatibility  with  versions  1.x,  it  was  in  reality  a  vastly  different 
operating  system.  Within  six  months  of  its  release,  version  2.0  gained  widespread  public 
acceptance.  In  addition,  popular  application  programs  such  as  Lotus  1-2-3  took  advantage 
of  the  features  of  this  new  version  of  MS-DOS  and  thus  helped  secure  its  future  as  the 
industry  standard  for  8086  processors. 

Versions  2.1  and  2.25 

The  world  into  which  version  2.0  of  MS-DOS  emerged  was  considerably  different  from  the 
one  in  which  version  1.0  made  its  debut.  When  IBM  released  its  original  PC,  the  business 
market  for  microcomputers  was  as  yet  undefined  —  if  not  in  scope,  at  least  in  terms  of  who 
and  what  would  dominate  the  field.  A  year  and  a  half  later,  when  the  PC/XT  came  on  the 
scene,  the  market  was  much  better  known.  It  had,  in  fact,  been  heavily  influenced  by  IBM 
itself.  There  were  still  many  MS-DOS  machines,  such  as  the  Tandy  2000  and  the  Hewlett 
Packard  HP150,  that  were  hardware  incompatible  with  the  IBM,  but  manufacturers  of  new 
computers  knew  that  IBM  was  a  force  to  consider  and  many  chose  to  compete  with  the 
IBM  PC  by  emulating  it.  Software  developers,  too,  had  gained  an  understanding  of  busi¬ 
ness  computing  and  were  confident  they  could  position  their  software  accurately  in  the 
enormous  MS-DOS  market. 
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In  such  an  environment,  concerns  about  the  existing  base  of  CP/M  software  faded  as 
developers  focused  their  attention  on  the  fast-growing  business  market  and  MS-DOS 
quickly  secured  its  position  as  an  industry  standard.  Now,  with  the  obstacles  to  MS-DOS 
diminished,  Microsoft  found  itself  with  a  new  concern:  maintaining  the  standard  it  had 
created.  Henceforth,  MS-DOS  had  to  be  many  things  to  many  people.  IBM  had  require¬ 
ments;  other  OEMs  had  requirements.  And  sometimes  these  requirements  conflicted. 


Hardware  Developers 

When  version  2.0  was  released,  IBM  was  already  planning  to  introduce  its  PCjr.  The  PCjr 
would  have  the  ability  to  run  programs  from  ROM  cartridges  and,  in  addition  to  using  half¬ 
height  5y4-inch  drives,  would  employ  a  slightly  different  disk-controller  architecture.  Be¬ 
cause  of  these  differences  from  the  standard  PC  line,  IBM’s  immediate  concern  was  for  a 
version  2.1  of  MS-DOS  modified  for  the  new  machine. 

For  the  longer  term,  IBM  was  also  planning  a  faster,  more  powerful  PC  with  a  20-megabyte 
fixed  disk.  This  prospect  meant  Microsoft  needed  to  look  again  at  its  file-management  sys¬ 
tem,  because  the  larger  storage  capacity  of  the  20-megabyte  disk  stretched  the  size  limita¬ 
tions  for  the  file  allocation  table  as  it  worked  in  version  2.0. 

However,  IBM’s  primary  interest  for  the  next  major  release  of  MS-DOS  was  networking. 
Microsoft  would  have  preferred  to  pursue  multitasking  as  the  next  stage  in  the  develop¬ 
ment  of  MS-DOS,  but  IBM  was  already  developing  its  IBM  PC  Network  Adapter,  a  plug-in 
card  with  an  80188  chip  to  handle  communications.  So  as  soon  as  version  2.0  was  released, 
the  MS-DOS  team,  again  headed  by  Zbikowski  and  Reynolds,  began  work  on  a  networking 
version  (3.0)  of  the  operating  system. 


Meanwhile . . . 

The  international  market  for  MS-DOS  was  not  significant  in  the  first  few  years  after  the 
release  of  the  IBM  PC  and  version  1.0  of  MS-DOS.  IBM  did  not,  at  first,  ship  its  Personal 
Computer  to  Europe,  so  Microsoft  was  on  its  own  there  in  promoting  MS-DOS.  In  1982,  the 
company  gained  a  significant  advantage  over  CP/M-86  in  Europe  by  concluding  an  agree¬ 
ment  with  Victor,  a  software  company  that  was  very  successful  in  Europe  and  had  already 
licensed  CP/M-86.  Working  closely  with  Victor,  Microsoft  provided  special  development 
support  for  its  graphics  adaptors  and  eventually  convinced  the  company  to  offer  its  pro¬ 
ducts  only  on  MS-DOS.  In  Japan,  the  most  popular  computers  were  Z80  machines,  and 
given  the  country’s  huge  installed  base  of  8-bit  machines,  l6-bit  computers  were  not  taking 
hold.  Mitsubishi,  however,  offered  a  l6-bit  computer.  Although  CP/M-86  was  Mitsubishi’s 
original  choice  for  an  operating  system,  Microsoft  helped  get  Multiplan  and  FORTRAN 
running  on  the  CP/M-86  system,  and  eventually  won  the  manufacturer’s  support  for 
MS-DOS. 
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Irresistible 
DOS  3.0 


Intematioyud  support,  Jile-sbaring  capa¬ 
bilities,  and  many’  other  features  in  DOS 
3-0  result  in  a  significantly  enlxinced 
operating  system. 


The  Ascent 
of  DOS 


•  Hands  On:  Operating  Systems 


MS-DOS  2.00:  A 
Hands-On  Tutorial 


Jthottgh  iht  anmmniement  of  the  i 
liter  XT  grabbed  the  headhnes  afte 


and  periphert 


A  sample  of  the  reviews  that  appeared 
with  each  new  version  of  MS-DOS. 


In  the  software  arena,  by  the  time  development  was  underway  on  the  2.x  releases  of 
MS-DOS,  Microsoft’s  other  customers  were  becoming  more  vocal  about  their  own  needs. 
Several  wanted  a  networking  capability,  adding  weight  to  IBM’s  request,  but  a  more  urgent 
need  for  many — a  need  not  shared  by  IBM  at  the  time — was  support  for  international 
products.  Specifically,  these  manufacturers  needed  a  version  of  MS-DOS  that  could  be  sold 
in  other  countries  —  a  version  of  MS-DOS  that  could  display  messages  in  other  languages 
and  adapt  to  country-specific  conventions,  such  as  date  and  time  formats. 

Microsoft,  too,  wanted  to  internationalize  MS-DOS,  so  the  MS-DOS  team,  while  modifying 
the  operating  system  to  support  the  PCjr,  also  added  functions  and  a  COUNTRY  command 
that  allowed  users  to  set  the  date  and  time  formats  and  other  country-dependent  variables 
in  the  CONFIG.SYS  file. 
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At  about  the  same  time,  another  international  requirement  appeared.  The  Japanese  market 
for  MS-DOS  was  growing,  and  the  question  of  supporting  7000  Kanji  characters  (ideo¬ 
grams)  arose.  The  difficulty  with  Kanji  is  that  it  requires  dual-byte  characters.  For  English 
and  most  European  character  sets,  one  byte  corresponds  to  one  character.  Japanese  char¬ 
acters,  however,  sometimes  use  one  byte,  sometimes  two.  This  variability  creates  prob¬ 
lems  in  parsing,  and  as  a  result  MS-DOS  had  to  be  modified  to  parse  a  string  from  the 
beginning,  rather  than  back  up  one  character  at  a  time. 

This  support  for  individual  country  formats  and  Kanji  appeared  in  version  2.01  of  MS-DOS. 
IBM  did  not  want  this  version,  so  support  for  the  PCjr,  developed  by  Zbikowski,  Reynolds, 
Ulloa,  and  Eric  Evans,  appeared  separately  in  version  2.1,  which  went  only  to  IBM  and  did 
not  include  the  modifications  for  international  MS-DOS. 

Different  customers,  different  versions 

As  early  as  version  1.25,  Microsoft  faced  the  problem  of  trying  to  satisfy  those  OEM  cus¬ 
tomers  that  wanted  to  have  the  same  version  of  MS-DOS  as  IBM.  Some,  such  as  COMPAQ, 
were  in  the  business  of  selling  100-percent  compatibility  with  IBM.  For  them,  any  differ¬ 
ence  between  their  version  of  the  operating  system  and  IBM’s  introduced  the  possibility  of 
incompatibility.  Satisfying  these  requests  was  difficult,  however,  and  it  was  not  until  ver¬ 
sion  3.1  that  Microsoft  was  able  to  supply  a  system  that  other  OEMs  agreed  was  identical 
with  IBM’s. 

Before  then,  to  satisfy  the  OEM  customers,  Microsoft  combined  versions  2.1  and  2.01  to 
create  version  2.11.  Although  IBM  did  not  accept  this  because  of  the  internationalization 
code,  version  2.11  became  the  standard  version  for  all  non-IBM  customers  running  any 
form  of  MS-DOS  in  the  2.x  series.  Version  2.11  was  sold  worldwide  and  translated  into 
about  10  different  languages.  Two  other  intermediate  versions  provided  support  for 
Hangeul  (the  Korean  character  set)  and  Chinese  Kanji. 
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Software  Concerns 

After  the  release  of  version  2.0,  Microsoft  also  gained  an  appreciation  of  the  importance — 
and  difficulty — of  supporting  the  people  who  were  developing  software  for  MS-DOS. 

Software  developers  worried  about  downward  compatibility.  They  also  worried  about 
upward  compatibility.  But  despite  these  concerns,  they  sometimes  used  programming 
practices  that  could  guarantee  neither.  When  this  happened  and  the  resulting  programs 
were  successful,  it  was  up  to  Microsoft  to  ensure  compatibility. 

For  example,  because  the  information  about  the  internals  of  the  BIOS  and  the  ROM  inter¬ 
face  had  been  published,  software  developers  could,  and  often  did,  work  directly  with  the 
hardware  in  order  to  get  more  speed.  This  meant  sidestepping  the  operating  system  for 
some  operations.  However,  by  choosing  to  work  at  the  lower  levels,  these  developers  lost 
the  protection  provided  by  the  operating  system  against  hardware  changes.  Thus,  when 
low-level  changes  were  made  in  the  hardware,  their  programs  either  did  not  work  or  did 
not  run  cooperatively  with  other  applications. 

Another  software  problem  was  the  continuing  need  for  compatibility  with  CP/M.  For 
example,  in  CP/M,  programmers  would  call  a  fixed  address  in  low  memory  in  order  to  re¬ 
quest  a  function;  in  MS-DOS,  they  would  request  operating-system  services  by  executing  a 
software  interrupt.  To  support  older  software,  the  first  version  of  MS-DOS  allowed  a  pro¬ 
gram  to  request  functions  by  either  method.  One  of  the  CP/M-based  programs  supported 
in  this  fashion  was  the  very  popular  WordStar.  Since  Microsoft  could  not  make  changes  in 
MS-DOS  that  would  make  it  impossible  to  run  such  a  widely  used  program,  each  new  ver¬ 
sion  of  MS-DOS  had  to  continue  supporting  CP/M-style  calls. 

A  more  pervasive  CP/M-related  issue  was  the  use  of  FCB-style  calls  for  file  and  record 
management.  The  version  1.x  releases  of  MS-DOS  had  used  FCB-style  calls  exclusively,  as 
had  CP/M.  Version  2.0  introduced  the  more  efficient  and  flexible  handle  calls,  but  Microsoft 
could  not  simply  abolish  the  old  FCB-style  calls,  because  so  many  popular  programs  used 
them.  In  fact,  some  of  Microsoft’s  own  languages  used  them.  So,  MS-DOS  had  to  support 
both  types  of  calls  in  the  version  2.x  series.  To  encourage  the  use  of  the  new  handle  calls, 
however,  Microsoft  made  it  easy  for  MS-DOS  users  to  upgrade  to  version  2.0.  In  addition, 
the  company  convinced  IBM  to  require  version  2.0  for  the  PC/XT  and  also  encouraged 
software  developers  to  require  2.0  for  their  applications. 

At  first,  both  software  developers  and  OEM  customers  were  reluctant  to  require  2.0 
because  they  were  concerned  about  problems  with  the  installed  user  base  of  1.0 
systems — requiring  version  2.0  meant  supporting  both  sets  of  calls.  Applications  also 
needed  to  be  able  to  detect  which  version  of  the  operating  system  the  user  was  running. 
For  versions  1.x,  the  programs  would  have  to  use  FCB  calls;  for  versions  2.x,  they  would 
use  the  file  handles  to  exploit  the  flexibility  of  MS-DOS  more  fully. 

All  told,  it  was  an  awkward  period  of  transition,  but  by  the  time  Microsoft  began  work  on 
version  3.0  and  the  support  for  IBM’s  upcoming  20-megabyte  fixed  disk,  it  had  become 
apparent  that  the  change  had  been  in  everyone’s  best  interest. 
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The  types  of  issues  that  began  to  emerge  as  Microsoft  worked  toward  version  3.0,  MS-DOS 
for  networks,  exaggerated  the  problems  of  compatibility  that  had  been  encountered 
before. 

First,  networking,  with  or  without  a  multitasking  capability,  requires  a  level  of  cooperation 
and  compatibility  among  programs  that  had  never  been  an  issue  in  earlier  versions  of 
MS-DOS.  As  described  by  Mark  Zbikowski,  one  of  the  principals  involved  in  the  project, 
“there  was  a  very  long  period  of  time  between  2.1  and  3.0 — almost  a  year  and  a  half.  Dur¬ 
ing  that  time,  we  believed  we  understood  all  the  problems  involved  in  making  DOS  a  net¬ 
working  product.  [But]  as  time  progressed,  we  realized  that  we  didn’t  fully  understand  it, 
either  from  a  compatibility  standpoint  or  from  an  operating-system  standpoint.  We  knew 
very  well  how  it  [DOS]  ran  in  a  single-tasking  environment,  but  we  started  going  to  this 
new  environment  and  found  places  where  it  came  up  short.” 

In  fact,  the  great  variability  in  programs  and  programming  approaches  that  MS-DOS 
supported  eventually  proved  to  be  one  of  the  biggest  obstacles  to  the  development  of  a 
sophisticated  networking  system  and;  in  the  longer  term,  to  the  addition  of  true 
multitasking. 

Further,  by  the  time  Microsoft  began  work  on  version  3.0,  the  programming  style  of  the 
MS-DOS  team  had  changed  considerably.  The  team  was  still  small,  with  a  core  group  of 
just  five  people:  Zbikowski,  Reynolds,  Peters,  Evans,  and  Mark  Bebic.  But  the  concerns  for 
maintainability  that  had  dominated  programming  in  larger  systems  had  percolated  down 
to  the  MS-DOS  environment.  Now,  the  desire  to  use  tricks  to  optimize  for  speed  had  to  be 
tempered  by  the  need  for  clarity  and  maintainability,  and  the  small  package  of  tightly 
written  code  that  was  the  early  MS-DOS  had  to  be  sacrificed  for  the  same  reasons. 


Version  3.0 

All  told,  the  work  on  version  3.0  of  MS-DOS  proved  to  be  long  and  difficult.  For  a  year  and 
a  half,  Microsoft  grappled  with  problems  of  software  incompatibility,  remote  file  manage¬ 
ment,  and  logical  device  independence  at  the  network  level.  Even  so,  when  IBM  was  ready 
to  announce  its  new  Personal  Computer  AT,  the  network  software  for  MS-DOS  was  not 
quite  ready,  so  in  August  1984,  Microsoft  released  version  3.0  to  IBM  without  network 
software. 

Version  3.0  supported  the  AT’s  larger  fixed  disk,  its  new  CMOS  clock,  and  its  high-capacity 
1.2-megabyte  floppy  disks.  It  also  provided  the  same  international  support  included  earlier 
in  versions  2.01  and  2.11.  These  features  were  made  available  to  Microsoft’s  other  OEM 
customers  as  version  3.05. 
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Aaron  Reynolds's  diagram  of  version  3.0’s  network  support,  sketched  out  to  enable  him  to  add  the fail  option 
to  Interrupt  24  and find  all  places  where  existing  parts  of  MS-DOS  were  affected.  Even  after  networking  had 
become  a  reality,  Reynolds  kept  this  diagram  pinned  to  his  office  wall  simply  because  “it  was  so  much  work 
to  put  together.  ’’ 
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The  Intel  80286  micro¬ 
processor,  the  chip  at 
the  heart  of  the  IBM 
PC/AT,  which  is  shown 
beside  it.  Version  3-0  of 
MS-DOS,  developed  for 
this  machine,  offered 
support  for  networks 
and  the  PC/ATs  1.2- 
megabyte  floppy  disk 
drive  and  built-in 
CMOS  clock. 


But  version  3.0  was  not  a  simple  extension  of  version  2.0.  In  laying  the  foundation  for  net¬ 
working,  the  MS-DOS  team  had  completely  redesigned  and  rewritten  the  DOS  kernel. 

Different  as  it  was  from  version  1.0,  version  2.0  had  been  built  on  top  of  the  same  structure. 
For  example,  whereas  file  requests  in  MS-DOS  1.0  used  FCBs,  requests  in  version  2.0  used 
file  handles.  However,  the  version  2.0  handle  calls  would  simply  parse  the  pathname  and 
then  use  the  underlying  FCB  calls  in  the  same  way  as  version  1.0.  The  redirected  input  and 
output  in  version  2.0  further  complicated  the  file-system  requests.  When  a  program  used 
one  of  the  CP/M-compatible  calls  for  character  input  or  output,  MS-DOS  2.0  first  opened  a 
handle  and  then  turned  it  back  into  an  FCB  call  at  a  lower  level.  Version  3.0  eliminated  this 
redundancy  by  eliminating  the  old  FCB  input/output  code  of  versions  1  and  2,  replacing  it 
with  a  standard  set  of  I/O  calls  that  could  be  called  directly  by  both  FCB  calls  and  handle 
calls.  The  look-alike  calls  for  CP/M-compatible  character  I/O  were  included  as  part  of  the 
set  of  handle  calls.  As  a  result  of  this  restructuring,  these  calls  were  distinctly  faster  in 
version  3.0  than  in  version  2.0. 

More  important  than  the  elimination  of  inefficiencies,  however,  was  the  fact  that  this  new 
structure  made  it  easier  to  handle  network  requests  under  the  ISO  Open  System  Intercon¬ 
nect  model  Microsoft  was  using  for  networking.  The  ISO  model  describes  a  number  of 
protocol  layers,  ranging  from  the  application-to-application  interface  at  the  top  level  down 
to  the  physical  link  —  plugging  into  the  network  —  at  the  lowest  level.  In  the  middle  is  the 
transport  layer,  which  manages  the  actual  transfer  of  data.  The  layers  above  the  transport 
layer  belong  to  the  realm  of  the  operating  system;  the  layers  below  the  transport  layer  are 
traditionally  the  domain  of  the  network  software  or  hardware. 

On  the  IBM  PC  network,  the  transport  layer  and  the  server  functions  were  handled  by 
IBM’s  Network  Adapter  card  and  the  task  of  MS-DOS  was  to  support  this  hardware.  For  its 
other  OEM  customers,  however,  Microsoft  needed  to  supply  both  the  transport  and  the 
server  functions  as  software.  Although  version  3.0  did  not  provide  this  general-purpose 
networking  software,  it  did  provide  the  basic  support  for  IBM’s  networking  hardware. 

The  support  for  IBM  consisted  of  redirector  and  sharer  software.  MS-DOS  used  an  ap¬ 
proach  to  networking  in  which  remote  requests  were  routed  by  a  redirector  that  was  able 
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to  interact  with  the  transport  layer  of  the  network.  The  transport  layer  was  composed  of 
the  device  drivers  that  could  reliably  transfer  data  from  one  part  of  the  network  to  another. 
Just  before  a  call  was  sent  to  the  newly  designed  low-level  file  I/O  code,  the  operating  sys¬ 
tem  determined  whether  the  call  was  local  or  remote.  A  local  call  would  be  allowed  to  fall 
through  to  the  local  file  I/O  code;  a  remote  call  would  be  passed  to  the  redirector  which, 
working  with  the  operating  system,  would  make  the  resources  on  a  remote  machine 
appear  as  if  they  were  local. 


Version  3.1 

Both  the  redirector  and  the  sharer  interfaces  for  IBM’s  Network  Adapter  card  were  in  place 
in  version  3.0  when  it  was  delivered  to  IBM,  but  the  redirector  itself  wasn’t  ready.  Version 
3.1,  completed  by  Zbikowski  and  Reynolds  and  released  three  months  later,<  completed  this 
network  support  and  made  it  available  in  the  form  of  Microsoft  Networks  for  use  on  non- 
IBM  network  cards. 

Microsoft  Networks  was  built  on  the  concept  of  “services”  and  “consumers.”  Services 
were  provided  by  a  file  server,  which  was  part  of  the  Networks  application  and  ran  on  a 
computer  dedicated  to  the  task.  Consumers  were  programs  on  various  network  machines. 
Requests  for  information  were  passed  at  a  high  level  to  the  file  server;  it  was  then  the 
responsibility  of  the  file  server  to  determine  where  to  find  the  information  on  the  disk. 
The  requesting  programs — the  consumers — did  not  need  any  knowledge  of  the  remote 
machine,  not  even  what  type  of  file  system  it  had. 

This  ability  to  pass  a  high-level  request  to  a  remote  server  without  having  to  know  the 
details  of  the  server’s  file  structure  allowed  another  level  of  generalization  of  the  system. 
In  MS-DOS  3.1,  different  types  of  file  systems  could  be  accessed  on  the  same  network.  It 
was  possible,  for  example,  to  access  a  XENIX  machine  across  the  network  from  an 
MS-DOS  machine  and  to  read  data  from  XENIX  files. 

Microsoft  Networks  was  designed  to  be  hardware  independent.  Yet  the  variability  of  the 
classes  of  programs  that  would  be  using  its  structures  was  a  major  problem  in  developing 
a  networking  system  that  would  be  transparent  to  the  user.  In  evaluating  this  variability, 
Microsoft  identified  three  types  of  programs: 

•  First  were  the  MS-DOS-compatible  programs.  These  used  only  the  documented 
software-interrupt  method  of  requesting  services  from  the  operating  system  and 
would  run  on  any  MS-DOS  machine  without  problems. 

•  Second  were  the  MS-DOS-based  programs.  These  would  run  on  IBM-compatible 
computers  but  not  necessarily  on  all  MS-DOS  machines. 

•  Third  were  the  programs  that  used  undocumented  features  of  MS-DOS  or  that 
addressed  the  hardware  directly.  These  programs  tended  to  have  the  best  perfor¬ 
mance  but  were  also  the  most  difficult  to  support. 

Of  these,  Microsoft  officially  encouraged  the  writing  of  MS-DOS-compatible  programs  for 
use  on  the  network. 


Section  I:  The  Development  of  MS-DOS  43 


1986 


Network  concerns 

The  file-access  module  was  changed  in  version  3.0  to  simplify  file  management  on  the 
network,  but  this  did  not  solve  all  the  problems.  For  instance,  MS-DOS  still  needed  to  han¬ 
dle  FCB  requests  from  programs  that  used  them,  but  many  programs  would  open  an  FCB 
and  never  close  it.  One  of  the  functions  of  the  server  was  to  keep  track  of  all  open  files 
on  the  network,  and  it  ran  into  difficulties  when  an  FCB  was  opened  50  or  100  times  and 
never  closed.  To  solve  this  problem,  Microsoft  introduced  an  FCB  cache  in  version  3.1  that 
allowed  only  four  FCBs  to  be  open  at  any  one  time.  If  a  fifth  FCB  was  opened,  the  least  re¬ 
cently  used  one  was  closed  automatically  and  released.  In  addition,  an  FCBS  command 
was  added  in  the  CONFIG.SYS  file  to  allow  the  user  or  network  manager  to  change  the 
maximum  number  of  FCBs  that  could  be  open  at  any  one  time  and  to  protect  some  of  the 
FCBs  from  automatic  closure. 

In  general,  the  logical  device  independence  that  had  been  a  goal  of  MS-DOS  acquired  new 
meaning — and  generated  new  problems — with  networking.  One  problem  concerned 
printers  on  the  network.  Commonly,  networks  are  used  to  allow  several  people  to  share  a 
printer.  The  network  could  easily  accommodate  a  program  that  would  open  the  printer, 
write  to  it,  and  close  it  again.  Some  programs,  however,  would  try  to  use  the  direct  IBM 
BIOS  interface  to  access  the  printer.  To  handle  this  situation,  Microsoft’s  designers  had  to 
develop  a  way  for  MS-DOS  to  intercept  these  BIOS  requests  and  filter  out  the  ones  the 
server  could  not  handle.  Once  this  was  accomplished,  version  3.1  was  able  to  handle  most 
types  of  printer  output  on  the  network  in  a  transparent  manner. 


Version  3.2 

In  January  1986,  Microsoft  released  another  revision  of  MS-DOS,  version  3.2,  which 
supported  3y2-inch  floppy  disks.  Version  3.2  also  moved  the  formatting  function  for  a 
device  out  of  the  FORMAT  utility  routine  and  into  the  device  driver,  eliminating  the  need 
for  a  special  hardware-dependent  program  in  addition  to  the  device  driver.  It  included  a 
sample  installable-block-device  driver  and,  finally,  benefited  the  users  and  manufacturers 
of  IBM-compatible  computers  by  including  major  rewrites  of  the  MS-DOS  utilities  to 
increase  compatibility  with  those  of  IBM. 
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The  Future 


Since  its  appearance  in  1981,  MS-DOS  has  taken  and  held  an  enviable  position  in  the 
microcomputer  environment.  Not  only  has  it  “taught”  millions  of  personal  computers 
“how  to  think,”  it  has  taught  equal  millions  of  people  how  to  use  computers.  Many  highly 
sophisticated  computer  users  can  trace  their  first  encounter  with  these  machines  to  the 
original  IBM  PC  and  version  1.0  of  MS-DOS.  The  MS-DOS  command  interface  is  the  one 
with  which  they  are  comfortable  and  it  is  the  MS-DOS  file  structure  that,  in  one  way  or 
another,  they  wander  through  with  familiarity. 

Microsoft  has  stated  its  commitment  to  ensuring  that,  for  the  foreseeable  future,  MS-DOS 
will  continue  to  evolve  and  grow,  changing  as  it  has  done  in  the  past  to  satisfy  the  needs  of 
its  millions  of  users.  In  the  long  term,  MS-DOS,  the  product  of  a  surprisingly  small  group  of 
gifted  people,  will  undoubtedly  remain  the  industry  standard  for  as  long  as  8086-based 
(and  to  some  extent,  80286-based)  microcomputers  exist  in  the  business  world.  The  story 
of  MS-DOS  will,  of  course,  remain  even  longer.  For  this  operating  system  has  earned  its 
place  in  microcomputing  history. 


JoAnne  Woodcock 
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An  Introduction  to  MS-DOS 


An  operating  system  is  a  set  of  interrelated  supervisory  programs  that  manage  and  control 
computer  processing.  In  general,  an  operating  ^stem  provides 

•  Storage  management 

•  Processing  management 

•  Security 

•  Human  interface 


Existing  operating  systems  for  microcomputers  fall  into  three  major  categories:  ROM 
monitors,  traditional  operating  systems,  and  operating  environments.  The  general  charac¬ 
teristics  of  the  three  categories  are  listed  in  Table  1-1. 


Table  1-1.  Characteristics  of  the  Three  Major  Types  of  Operating  Systems. 


Traditional 

ROM  Operating  Operating 

Monitor  System  Environment 


Complexity  Low  Medium 

Built  on  Hardware  BIOS 

Delivered  on  ROM  Disk 

Programs  on  ROM  Disk 

Peripheral  support  Physical  Logical 

Disk  access  Sector  File  system 

Example  PC  ROM  BIOS  MS-DOS 


High 

Operating  system 

Disk 

Disk 

Logical 

File  system 

Microsoft  Windows 


A  ROM  monitor  is  the  simplest  type  of  operating  system.  It  is  designed  for  a  particular 
hardware  configuration  and  provides  a  program  with  basic — and  often  direct — access  to 
peripherals  attached  to  the  computer.  Programs  coupled  with  a  ROM  monitor  are  often 
used  for  dedicated  applications  such  as  controlling  a  microwave  oven  or  controlling  the 
engine  of  a  car. 

A  traditional  microcomputer  operating  system  is  built  on  top  of  a  ROM  monitor,  or  BIOS 
(basic  input/output  system),  and  provides  additional  features  such  as  a  file  system  and  log¬ 
ical  access  to  peripherals.  (Logical  access  to  peripherals  allows  applications  to  run  in  a 
hardware-independent  manner.)  A  traditional  operating  system  also  stores  programs  in 
files  on  peripheral  storage  devices  and,  on  request,  loads  them  into  memory  for  execution. 
MS-DOS  is  a  traditional  operating  system. 

An  operating  environment  is  built  on  top  of  a  traditional  operating  system.  The  operating 
environment  provides  additional  services,  such  as  common  menu  and  forms  support,  that 
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simplify  program  operation  and  make  the  user  interface  more  consistent.  Microsoft 
Windows  is  an  operating  environment. 


MS-DOS  System  Components 

The  Microsoft  Disk  Operating  System,  MS-DOS,  is  a  traditional  microcomputer  operating 
system  that  consists  of  five  major  components: 

•  The  operating-system  loader 

•  The  MS-DOS  BIOS 

•  The  MS-DOS  kernel 

•  The  user  interface  (shell) 

•  Support  programs 

Each  of  these  is  introduced  briefly  in  the  following  pages.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Structure  of  ms-dos:  The  Components  of  MS-DOS. 

The  operating-system  loader 

The  operating-system  loader  brings  the  operating  system  from  the  startup  disk  into  RAM. 

The  complete  loading  process,  called  bootstrapping,  is  often  complex,  and  multiple 
loaders  may  be  involved.  (The  term  bootstrapping  came  about  because  each  level  pulls  up 
the  next  part  of  the  system,  like  pulling  up  on  a  pair  of  bootstraps.)  For  example,  in  most 
standard  MS-DOS-based  microcomputer  implementations,  the  ROM  loader,  which  is  the 
first  program  the  microcomputer  executes  when  it  is  turned  on  or  restarted,  reads  the  disk 
bootstrap  loader  from  the  first  (boot)  sector  of  the  startup  disk  and  executes  it.  The  disk 
bootstrap  loader,  in  turn,  reads  the  main  portions  of  MS-DOS — MSDOS.SYS  and  lO.SYS 
(IBMDOS.COM  and  IBMBIO.COM  with  PC-DOS) — from  conventional  disk  files  into  mem¬ 
ory.  The  special  module  SYSINIT  within  MSDOS.SYS  then  initializes  MS-DOS’s  tables  and 
buffers  and  discards  itself.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Struc¬ 
ture  OF  MS-DOS:  MS-DOS  Storage  Devices. 

(The  term  loader  is  also  used  to  refer  to  the  portion  of  the  operating  system  that  brings 
application  programs  into  memory  for  execution.  This  loader  is  different  from  the  ROM 
loader  and  the  operating-system  loader.) 

The  MS-DOS  BIOS 

The  MS-DOS  BIOS,  loaded  from  the  file  lO.SYS  during  system  initialization,  is  the  layer  of 
the  operating  system  that  sits  between  the  operating-system  kernel  and  the  hardware.  An 
application  performs  input  and  output  by  making  requests  to  the  operating-system  kernel, 
which,  in  turn,  calls  the  MS-DOS  BIOS  routines  that  access  the  hardware  directly.  See 
SYSTEM  CALLS.  This  division  of  function  allows  application  programs  to  be  written  in  a 
hardware-independent  manner. 

The  MS-DOS  BIOS  consists  of  some  initialization  code  and  a  collection  of  device  drivers. 
(A  device  driver  is  a  specialized  program  that  provides  support  for  a  specific  device  such  as 
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a  display  or  serial  port.)  The  device  drivers  are  responsible  for  hardware  access  and  for  the 
interrupt  support  that  allows  the  associated  devices  to  signal  the  microprocessor  that  they 
need  service. 

The  device  drivers  contained  in  the  file  lO.SYS,  which  are  always  loaded  during  system 
initialization,  are  sometimes  referred  to  as  the  resident  drivers.  With  MS-DOS  versions  2.0 
and  later,  additional  device  drivers,  called  installable  drivers,  can  optionally  be  loaded  dur¬ 
ing  system  initialization  as  a  result  of  DEVICE  directives  in  the  system’s  configuration  file. 
See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Installable 
Device  Drivers;  USER  COMMANDS:  config.sys:device. 

The  MS-DOS  kernel 

The  services  provided  to  application  programs  by  the  MS-DOS  kernel  include 

•  Process  control 

•  Memory  management 

•  Peripheral  support 

•  A  file  system 

The  MS-DOS  kernel  is  loaded  from  the  file  MSDOS.SYS  during  system  initialization. 

Process  control 

Process,  or  task,  control  includes  program  loading,  task  execution,  task  termination,  task 
scheduling,  and  intertask  communication. 

Although  MS-DOS  is  not  a  multitasking  operating  system,  it  can  have  multiple  programs 
residing  in  memory  at  the  same  time.  One  program  can  invoke  another,  which  then 
becomes  the  active  (foreground)  task.  When  the  invoked  task  terminates,  the  invoking 
program  again  becomes  the  foreground  task.  Because  these  tasks  never  execute  simulta¬ 
neously,  this  stack-like  operation  is  still  considered  to  be  a  single-tasking  operating 
system. 

MS-DOS  does  have  a  few  “hooks”  that  allow  certain  programs  to  do  some  multitasking 
on  their  own.  For  example,  terminate-and-stay-resident  (TSR)  programs  such  as  PRINT 
use  these  hooks  to  perform  limited  concurrent  processing  by  taking  control  of  system 
resources  while  MS-DOS  is  “idle,”  and  the  Microsoft  Windows  operating  environment 
adds  support  for  nonpreemptive  task  switching. 

The  traditional  intertask  communication  methods  include  semaphores,  queues,  shared 
memory,  and  pipes.  Of  these,  MS-DOS  formally  supports  only  pipes.  (A  pipe  is  a  logical, 
unidirectional,  sequential  stream  of  data  that  is  written  by  one  program  and  read  by 
another.)  The  data  in  a  pipe  resides  in  memory  or  in  a  disk  file,  depending  on  the  imple¬ 
mentation;  MS-DOS  uses  disk  files  for  intermediate  storage  of  data  in  pipes  because  it 
is  a  single-tasking  operating  system. 

Memory  management 

Because  the  amount  of  memory  a  program  needs  varies  from  program  to  program,  the 
traditional  operating  system  ordinarily  provides  memory-management  functions.  Memory 
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requirements  can  also  vary  during  program  execution,  and  memory  management  is 
especially  necessary  when  two  or  more  programs  are  present  in  memory  at  the  same  time. 

MS-DOS  memory  management  is  based  on  a  pool  of  variable-size  memory  blocks.  The 
two  basic  memory-management  actions  are  to  allocate  a  block  from  the  pool  and  to  return 
an  allocated  block  to  the  pool.  MS-DOS  allocates  program  space  from  the  pool  when  the 
program  is  loaded;  programs  themselves  can  allocate  additional  memory  from  the  pool. 
Many  programs  perform  their  own  memory  management  by  using  a  local  memory  pool,  or 
heap — an  additional  memory  block  allocated  from  the  operating  system  that  the  applica¬ 
tion  program  itself  divides  into  blocks  for  use  by  its  various  routines.  See  PROGRAMMING 
IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Memory  Management. 

Peripheral  support 

The  operating  system  provides  peripheral  support  to  programs  through  a  set  of  operating- 
system  calls  that  are  translated  by  the  operating  system  into  calls  to  the  appropriate  device 
driver. 

Peripheral  support  can  be  a  direct  logical-to-physical-device  translation  or  the  operating 
system  can  interject  additional  features  or  translations.  Keyboards,  displays,  and  printers 
usually  require  only  logical-to-physical-device  translations;  that  is,  the  data  is  transferred 
between  the  application  program  and  the  physical  device  with  minimal  alterations,  if  any, 
by  the  operating  system.  The  data  provided  by  clock  devices,  on  the  other  hand,  must  be 
transformed  to  operating-system-dependent  time  and  date  formats.  Disk  devices — and 
block  devices  in  general — have  the  greatest  number  of  features  added  by  the  operating 
system.  See  The  File  System  below. 

As  stated  earlier,  an  application  need  not  be  concerned  with  the  details  of  peripheral 
devices  or  with  any  special  features  the  devices  might  have.  Because  the  operating  system 
takes  care  of  all  the  logical-to-physical-device  translations,  the  application  program  need 
only  make  requests  of  the  operating  system. 

The  file  system 

The  file  system  is  one  of  the  largest  portions  of  an  operating  system.  A  file  system  is  built 
on  the  storage  medium  of  a  block  device  (usually  a  floppy  disk  or  a  fixed  disk)  by  mapping 
a  directory  structure  and  files  onto  the  physical  unit  of  storage.  A  file  system  on  a  disk 
contains,  at  a  minimum,  allocation  information,  a  directory,  and  space  for  files.  See 
PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Structure  of  ms-dos:  MS-DOS 
Storage  Devices. 

The  file  allocation  information  can  take  various  forms,  depending  on  the  operating  sys¬ 
tem,  but  all  forms  basically  track  the  space  used  by  files  and  the  space  available  for  new 
data.  The  directory  contains  a  list  of  the  files  stored  on  the  device,  their  sizes,  and  informa¬ 
tion  about  where  the  data  for  each  file  is  located. 

Several  different  approaches  to  file  allocation  and  directory  entries  exist.  MS-DOS  uses  a 
particular  allocation  method  called  a  file  allocation  table  (FAT)  and  a  hierarchical  directory 
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Structure.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Structure  of  ms-dos: 
MS-DOS  Storage  Devices;  Programming  for  ms-dos:  Disk  Directories  and  Volume  Labels. 

The  file  granularity  available  through  the  operating  system  also  varies  depending  on  the 
implementation.  Some  systems,  such  as  MS-DOS,  have  files  that  are  accessible  to  the  byte 
level;  others  are  restricted  to  a  fixed  record  size. 

File  systems  are  sometimes  extended  to  map  character  devices  as  if  they  were  files.  These 
device  “files”  can  be  opened,  closed,  read  from,  and  written  to  like  normal  disk  files,  but 
all  transactions  occur  directly  with  the  specified  character  device.  Device  files  provide  a 
useful  consistency  to  the  environment  for  application  programs;  MS-DOS  supports  such 
files  by  assigning  a  reserved  logical  name  (such  as  CON  or  PRN)  to  each  character  device. 

The  user  interface 

The  user  interface  for  an  operating  system,  also  called  a  shell  or  command  processor,  is 
generally  a  conventional  program  that  allows  the  user  to  interact  with  the  operating  sys¬ 
tem  itself.  The  default  MS-DOS  user  interface  is  a  replaceable  shell  program  called 
COMMAND.COM. 

One  of  the  fundamental  tasks  of  a  shell  is  to  load  a  program  into  memory  on  request  and 
pass  control  of  the  system  to  the  program  so  that  the  program  can  execute.  When  the  pro¬ 
gram  terminates,  control  returns  to  the  shell,  which  prompts  the  user  for  another  com¬ 
mand.  In  addition,  the  shell  usually  includes  functions  for  file  and  directory  maintenance 
and  display.  In  theory,  most  of  these  functions  could  be  provided  as  programs,  but  making 
them  resident  in  the  shell  allows  them  to  be  accessed  more  quickly.  The  tradeoff  is  mem¬ 
ory  space  versus  speed  and  flexibility.  Early  microcomputer-based  operating  systems  pro¬ 
vided  a  minimal  number  of  resident  shell  commands  because  of  limited  memory  space; 
modern  operating  systems  such  as  MS-DOS  include  a  wide  variety  of  these  functions  as 
internal  commands. 

Support  programs 

The  MS-DOS  software  includes  support  programs  that  provide  access  to  operating-system 
facilities  not  supplied  as  resident  shell  commands  built  into  COMMAND.COM.  Because 
these  programs  are  stored  as  executable  files  on  disk,  they  are  essentially  the  same  as  ap¬ 
plication  programs  and  MS-DOS  loads  and  executes  them  as  it  would  any  other  program. 

The  support  programs  provided  with  MS-DOS,  often  referred  to  as  external  commands, 
include  disk  utilities  such  as  FORMAT  and  CHKDSK  and  more  general  support  programs 
such  as  EDLIN  (a  line-oriented  text  editor)  and  PRINT  (a  TSR  utility  that  allows  files  to  be 
printed  while  another  program  is  running).  See  USER  COMMANDS. 

MS-DOS  releases 

MS-DOS  and  PC-DOS  have  been  released  in  a  number  of  forms,  starting  in  1981.  See  THE 
DEVELOPMENT  OF  MS-DOS.  The  major  MS-DOS  and  PC-DOS  implementations  are  sum¬ 
marized  in  the  following  table. 
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Version  Date  Special  Characteristics 

1981  First  operating  system  for  the  IBM  PC 
Record-oriented  files 

1982  Double-sided-disk  support 

1982  First  OEM  release  of  MS-DOS 

1983  Operating  system  for  the  IBM  PC/XT 
UNDC/XENIX-like  file  system 
Installable  device  drivers 
Byte-oriented  files 
Support  for  fixed  disks 

Operating  system  for  the  IBM  PCjr 
Internationalization  support 
2.0x  bug  fixes 

1984  Operating  system  for  the  IBM  PCAT 
Support  for  1.2  MB  floppy  disks 
Support  for  large  fixed  disks 
Support  for  file  and  record  locking 
Application  control  of  print  spooler 

1984  Support  for  MS  Networks 

1986  3.5-inch  floppy-disk  support 
Disk  track  formatting  support  added  to 
device  drivers 

1987  Support  for  the  IBM  PS/2 
Enhanced  internationalization  support 
Improved  file-system  performance 
Partitioning  support  for  disks  with  capacity 
above  32  MB 

PC-DOS  version  1.0  was  the  first  commercial  version  of  MS-DOS.  It  was  developed  for  the 
original  IBM  PC,  which  was  typically  shipped  with  64  KB  of  memory  or  less.  MS-DOS  and 
PC-DOS  versions  1.x  were  similar  in  many  ways  to  CP/M,  the  popular  operating  system  for 
8-bit  microcomputers  based  on  the  Intel  8080  (the  predecessor  of  the  8086).  These  ver¬ 
sions  of  MS-DOS  used  a  single-level  file  system  with  no  subdirectory  support  and  did  not 
support  installable  device  drivers  or  networks.  Programs  accessed  files  using  file  control 
blocks  (FCBs)  similar  to  those  found  in  CP/M  programs.  File  operations  were  record 
oriented,  again  like  CP/M,  although  record  sizes  could  be  varied  in  MS-DOS. 

Although  they  retained  compatibility  with  versions  1.x,  MS-DOS  and  PC-DOS  versions  2.x 
represented  a  major  change.  In  addition  to  providing  support  for  fixed  disks,  the  new  ver¬ 
sions  switched  to  a  hierarchical  file  system  like  that  found  in  UNDC/XENIX  and  to  file- 
handle  access  instead  of  FCBs.  (A  file  handle  is  a  l6-bit  number  used  to  reference  an  inter¬ 
nal  table  that  MS-DOS  uses  to  keep  track  of  currently  open  files;  an  application  program 
has  no  access  to  this  internal  table.)  The  UNIX/XENIX-style  file  functions  allow  files  to  be 
treated  as  a  byte  stream  instead  of  as  a  collection  of  records.  Applications  can  read  or  write 
1  to  65535  bytes  in  a  single  operation,  starting  at  any  byte  offset  within  the  file.  Filenames 


PC-DOS  1.0 

PC-DOS  1.1 
MS-DOS  1.25 
MS-DOS/PC-DOS  2.0 


PC-DOS  2.1 
MS-DOS  2.11 

MS-DOS/PC-DOS  3.0 


MS-DOS/PC-DOS  3.1 
MS-DOS/PC-DOS  3.2 


MS-DOS/PC-DOS  3.3 
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used  for  opening  a  file  are  passed  as  text  strings  instead  of  being  parsed  into  an  FCB. 
Installable  device  drivers  were  another  major  enhancement. 

MS-DOS  and  PC-DOS  versions  3.x  added  a  number  of  valuable  features,  including  support 
for  the  added  capabilities  of  the  IBM  PCAT,  for  larger-capacity  disks,  and  for  file-locking 
and  record-locking  functions.  Network  support  was  added  by  providing  hooks  for  a  redi¬ 
rector  (an  additional  operating-system  module  that  has  the  ability  to  redirect  local  system 
service  requests  to  a  remote  system  by  means  of  a  local  area  network). 

With  all  these  changes,  MS-DOS  remains  a  traditional  single-tasking  operating  system.  It 
provides  a  large  number  of  system  services  in  a  transparent  fashion  so  that,  as  long  as  they 
use  only  the  MS-DOS-supplied  services  and  refrain  from  using  hardware-specific  opera¬ 
tions,  applications  developed  for  one  MS-DOS  machine  can  usually  run  on  another. 


Basic  MS-DOS  Requirements 

Foremost  among  the  requirements  for  MS-DOS  is  an  Intel  8086-compatible  microproces¬ 
sor.  See  Specific  Hardware  Requirements  below. 

The  next  requirement  is  the  ROM  bootstrap  loader  and  enough  RAM  to  contain  the 
MS-DOS  BIOS,  kernel,  and  shell  and  an  application  program.  The  RAM  must  start  at  ad¬ 
dress  OOOOiOOOOH  and,  to  be  managed  by  MS-DOS,  must  be  contiguous.  The  upper  limit 
for  RAM  is  the  limit  placed  upon  the  system  by  the  8086  family — 1  MB. 

The  final  requirement  for  MS-DOS  is  a  set  of  devices  supported  by  device  drivers,  includ¬ 
ing  at  least  one  block  device,  one  character  device,  and  a  clock  device.  The  block  device  is 
usually  the  boot  disk  device  (the  disk  device  from  which  MS-DOS  is  loaded);  the  character 
device  is  usually  a  keyboard/display  combination  for  interaction  with  the  user;  the  clock 
device,  required  for  time-of-day  and  date  support,  is  a  hardware  counter  driven  in  a  sub¬ 
multiple  of  one  second. 

Specific  hardware  requirements 

MS-DOS  uses  several  hardware  components  and  has  specific  requirements  for  each.  These 
components  include 

•  An  8086-family  microprocessor 

•  Memory 

•  Peripheral  devices 

•  A  ROM  BIOS  (PC-DOS  only) 

The  microprocessor 

MS-DOS  runs  on  any  machine  that  uses  a  microprocessor  that  executes  the  8086/8088 
instruction  set,  including  the  Intel  8086, 80C86, 8088, 80186,  80188, 80286,  and  80386  and 
the  NEC  V20,  V30,  and  V40. 
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The  80186  and  80188  are  versions  of  the  8086  and  8088,  integrated  in  a  single  chip  with 
direct  memory  access,  timer,  and  interrupt  support  functions.  PC-DOS  cannot  usually  run 
on  the  80186  or  80188  because  these  chips  have  internal  interrupt  and  interface  register 
addresses  that  conflict  with  addresses  used  by  the  PC  ROM  BIOS.  See  PROGRAMMING 
IN  THE  MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Hardware  Interrupt  Handlers. 
MS-DOS,  however,  does  not  have  address  requirements  that  conflict  with  those  interrupt 
and  interface  areas. 

The  80286  has  an  extended  instruction  set  and  two  operating  modes:  real  and  protected. 
Real  mode  is  compatible  with  the  8086/8088  and  runs  MS-DOS.  Protected  mode,  used  by 
operating  systems  like  UNIX/XENIX  and  MS  OS/2,  is  partially  compatible  with  real  mode 
in  terms  of  instructions  but  provides  access  to  16  MB  of  memory  versus  only  1  MB  in  real 
mode  (the  limit  of  the  8086/8088). 

The  80386  adds  further  instructions  and  a  third  mode  called  virtual  86  mode.  The  80386 
instructions  operate  in  either  a  l6-bit  or  a  32-bit  environment.  MS-DOS  can  run  on  the 
80386  in  real  or  virtual  86  mode,  although  the  latter  requires  additional  support  in  the  form 
of  a  virtual  machine  monitor  such  as  Windows  /386. 

Memory  requirements 

At  a  minimum,  MS-DOS  versions  1.x  require  64  KB  of  contiguous  RAM  from  the  base  of 
memory  to  do  useful  work;  versions  2.x  and  3.x  need  at  least  128  KB.  The  maximum  is 
1  MB,  although  most  MS-DOS  machines  have  a  640  KB  limit  for  IBM  PC  compatibility. 
MS-DOS  can  use  additional  noncontiguous  RAM  for  a  RAMdisk  if  the  proper  device  driver 
is  included.  (Other  uses  for  noncontiguous  RAM  include  buffers  for  video  displays,  fixed 
disks,  and  network  adapters.) 

PC-DOS  has  the  same  minimum  memory  requirements  but  has  an  upper  limit  of  640  KB 
on  the  initial  contiguous  RAM,  which  is  generally  referred  to  as  conventional  memory. 
This  limit  was  imposed  by  the  architecture  of  the  original  IBM  PC,  with  the  remaining 
area  above  640  KB  reserved  for  video  display  buffers,  fixed  disk  adapters,  and  the  ROM 
BIOS.  Some  of  the  reserved  areas  include 


Base  Address  Size  Obytes) 


Description 


A000:0000H 

B000:0000H 

B800:0000H 

C800:0000H 

F000:0000H 


10000H(64KB) 
1000H(4KB) 
4000H  (16  KB) 
4000H  (16  KB) 
10000H(64KB) 


EGA  video  buffer 
Monochrome  video  buffer 
Color/graphics  video  buffer 
Fixed-disk  ROM 
PC  ROM  BIOS  and  ROM  BASIC 


The  bottom  1024  bytes  of  system  RAM  (locations  00000-003FFH)  are  used  by  the  micro¬ 
processor  for  an  interrupt  vector  table — that  is,  a  list  of  addresses  for  interrupt  handler 
routines.  MS-DOS  uses  some  of  the  entries  in  this  table,  such  as  the  vectors  for  interrupts 
20H  through  2FH,  to  store  addresses  of  its  own  tables  and  routines  and  to  provide  linkage 
to  its  services  for  application  programs.  The  IBM  PC  ROM  BIOS  and  IBM  PC  BASIC  use 
many  additional  vectors  for  the  same  purposes. 


58 


The  MS-DOS  Encyclopedia 


Article  1:  An  Introduction  to  MS-DOS 


Peripheral  devices 

MS-DOS  can  support  a  wide  variety  of  devices,  including  floppy  disks,  fixed  disks,  CD 
ROMs,  RAMdisks,  and  digital  tape  drives.  The  required  peripheral  support  for  MS-DOS  is 
provided  by  the  MS-DOS  BIOS  or  by  installable  device  drivers. 

Five  logical  devices  are  provided  in  a  basic  MS-DOS  system: 


Device  Name  Description 


CON 
PRN 
AUX 
CLOCK$ 
Varies  (A-E) 


Console  input  and  output 
Printer  output 
Auxiliary  input  and  output 
Date  and  time  support 
One  block  device 


These  five  logical  devices  can  be  implemented  with  a  BIOS  supporting  a  minimum  of 
three  physical  devices:  a  keyboard  and  display,  a  timer  or  clock/calendar  chip  that  can 
provide  a  hardware  interrupt  at  regular  intervals,  and  a  block  storage  device.  In  such  a 
minimum  case,  the  printer  and  auxiliary  device  are  simply  aliases  for  the  console  device. 
However,  most  MS-DOS  systems  support  several  additional  logical  and  physical  devices. 
See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos: 
Character  Device  Input  and  Output. 

The  MS-DOS  kernel  provides  one  additional  device:  the  NUL  device.  NUL  is  a  “bit 
bucket” — that  is,  anything  written  to  NUL  is  simply  discarded.  Reading  from  NUL  always 
returns  an  end-of-file  marker.  One  common  use  for  the  NUL  device  is  as  the  redirected 
output  device  of  a  command  or  application  that  is  being  run  in  a  batch  file;  this  redirection 
prevents  screen  clutter  and  disruption  of  the  batch  file's  menus  and  displays. 

The  ROM  BIOS 

MS-DOS  requires  no  ROM  support  (except  that  most  bootstrap  loaders  reside  in  ROM) 
and  does  not  care  whether  device-driver  support  resides  in  ROM  or  is  part  of  the  MS-DOS 
lO.SYS  file  loaded  at  initialization.  PC-DOS,  on  the  other  hand,  uses  a  very  specific  ROM 
BIOS.  The  PC  ROM  BIOS  does  not  provide  device  drivers;  rather,  it  provides  support  rou¬ 
tines  used  by  the  device  drivers  found  in  IBMBIO.COM  (the  PC-DOS  version  of  lO.SYS). 
The  support  provided  by  a  PC  ROM  BIOS  includes 

•  Power-on  self  test  (POST) 

•  Bootstrap  loader 

•  Keyboard 

•  Displays  (monochrome  and  color/graphics  adapters) 

•  Serial  ports  1  and  2 

•  Parallel  printer  ports  1,  2,  and  3 

•  Clock 

•  Print  screen 
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The  PC  ROM  BIOS  loader  routine  searches  the  ROM  space  above  the  PC-DOS  640  KB  limit 
for  additional  ROMs.  The  IBM  fixed-disk  adapter  and  enhanced  graphics  adapter  (EGA) 
contain  such  ROMs.  (The  fixed-disk  ROM  also  includes  an  additional  loader  routine  that 
allows  the  system  to  start  from  the  fixed  disk.) 


Summary 

MS-DOS  is  a  widely  accepted  traditional  operating  system.  Its  consistent  and  well-defined 
interface  makes  it  one  of  the  easier  operating  systems  to  adapt  and  program. 

MS-DOS  is  also  a  growing  operating  system — each  version  has  added  more  features  yet 
made  the  system  easier  to  use  for  both  end-users  and  programmers.  In  addition,  each  ver¬ 
sion  has  included  more  support  for  different  devices,  from  5.25-inch  floppy  disks  to  high- 
density  3.5-inch  floppy  disks.  As  the  hardware  continues  to  evolve  and  user  needs  become 
more  sophisticated,  MS-DOS  too  will  continue  to  evolve. 


William  Wong 


60 


The  MS-DOS  Encyclopedia 


Article  2:  The  Components  of  MS-DOS 


Article  2 

The  Components  of  MS-DOS 


MS-DOS  is  a  modular  operating  system  consisting  of  multiple  components  with  special¬ 
ized  functions.  When  MS-DOS  is  copied  into  memory  during  the  loading  process,  many  of 
its  components  are  moved,  adjusted,  or  discarded.  However,  when  it  is  running,  MS-DOS 
is  a  relatively  static  entity  and  its  components  are  predictable  and  easy  to  study.  Therefore, 
this  article  deals  first  with  MS-DOS  in  its  running  state  and  later  with  its  loading  behavior. 


The  Major  Elements 

MS-DOS  consists  of  three  major  modules: 


Module  MS-DOS  Filename  PC-DOS  Filename 

MS-DOS  BIOS  lO.SYS  IBMBIO.COM 

MS-DOS  kernel  MSDOS.SYS  IBMDOS.COM 

MS-DOS  shell  COMMAND.COM  COMMAND.COM 

During  system  initialization,  these  modules  are  loaded  into  memory,  in  the  order  given, 
just  above  the  interrupt  vector  table  located  at  the  beginning  of  memory.  All  three  modules 
remain  in  memory  until  the  computer  is  reset  or  turned  off  (The  loader  and  system  initial¬ 
ization  modules  are  omitted  from  this  list  because  they  are  discarded  as  soon  as  MS-DOS 
is  running.  See  Loading  MS-DOS  below.) 

The  MS-DOS  BIOS  is  supplied  by  the  original  equipment  manufacturer  (OEM)  that 
distributes  MS-DOS,  usually  for  a  particular  computer.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Structure  of  ms-dos:  An  Introduction  to  MS-DOS.  The  kernel 
is  supplied  by  Microsoft  and  is  the  same  across  all  OEMs  for  a  particular  version  of 
MS-DOS — that  is,  no  modifications  are  made  by  the  OEM.  The  shell  is  a  replaceable 
module  that  can  be  supplied  by  the  OEM  or  replaced  by  the  user;  the  default  shell, 
COMMAND.COM,  is  supplied  by  Microsoft. 

The  MS-DOS  BIOS 

The  file  lO.SYS  contains  the  MS-DOS  BIOS  and  the  MS-DOS  initialization  module, 
SYSINIT.  The  MS-DOS  BIOS  is  customized  for  a  particular  machine  by  an  OEM.  SYSINIT 
is  supplied  by  Microsoft  and  is  put  into  lO.SYS  by  the  OEM  when  the  file  is  created.  See 
Loading  MS-DOS  below. 
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The  MS-DOS  BIOS  consists  of  a  list  of  resident  device  drivers  and  an  additional  initializa¬ 
tion  module  created  by  the  OEM.  The  device  drivers  appear  first  in  lO.SYS  because  they 
remain  resident  after  lO.SYS  is  initialized;  the  MS-DOS  BIOS  initialization  routine  and 
SYSINIT  are  usually  discarded  after  initialization. 

The  minimum  set  of  resident  device  drivers  is  CON,  PRN,  AUX,  CLOCK$,  and  the  driver 
for  one  block  device.  The  resident  character-device  drivers  appear  in  the  driver  list  before 
the  resident  block-device  drivers;  installable  character-device  drivers  are  placed  ahead  of 
the  resident  device  drivers  in  the  list;  installable  block-device  drivers  are  placed  after  the 
resident  device  drivers  in  the  list.  This  sequence  allows  installable  character-device  drivers 
to  supersede  resident  drivers.  The  NUL  device  driver,  which  must  be  the  first  driver  in  the 
chain,  is  contained  in  the  MS-DOS  kernel. 

Device  driver  code  can  be  split  between  lO.SYS  and  ROM.  For  example,  most  MS-DOS  sys¬ 
tems  and  all  PC-DOS-compatible  systems  have  a  ROM  BIOS  that  contains  primitive  device 
support  routines.  These  routines  are  generally  used  by  resident  and  installable  device 
drivers  to  augment  routines  contained  in  RAM.  (Placing  the  entire  driver  in  RAM  makes 
the  driver  dependent  on  a  particular  hardware  configuration;  placing  part  of  the  driver  in 
ROM  allows  the  MS-DOS  BIOS  to  be  paired  with  a  particular  ROM  interface  that  remains 
constant  for  many  different  hardware  configurations.) 

The  lO.SYS  file  is  an  absolute  program  image  and  does  not  contain  relocation  information. 
The  routines  in  lO.SYS  assume  that  the  CS  register  contains  the  segment  at  which  the  file  is 
loaded.  Thus,  lO.SYS  has  the  same  64  KB  restriction  as  a  .COM  file.  See  PROGRAMMING 
IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Structure  of  an  Application 
Program,  Larger  lO.SYS  files  are  possible,  but  all  device  driver  headers  must  lie  in  the  first 
64  KB  and  the  code  must  rely  on  its  own  segment  arithmetic  to  access  routines  outside 
the  first  64  KB. 

The  MS-DOS  kernel 

The  MS-DOS  kernel  is  the  heart  of  MS-DOS  and  provides  the  functions  found  in  a  tradi¬ 
tional  operating  system.  It  is  contained  in  a  single  proprietary  file,  MSDOS.SYS,  supplied 
by  Microsoft  Corporation.  The  kernel  provides  its  support  functions  (referred  to  as  system 
functions)  to  application  programs  in  a  hardware-independent  manner  and,  in  turn,  is  iso¬ 
lated  from  hardware  characteristics  by  relying  on  the  driver  routines  in  the  MS-DOS  BIOS 
to  perform  physical  input  and  output  operations. 

The  MS-DOS  kernel  provides  the  following  services  through  the  use  of  device  drivers: 

•  File  and  directory  management 

•  Character  device  input  and  output 

•  Time  and  date  support 

It  also  provides  the  following  non-device-related  functions: 

•  Memory  management 

•  Task  and  environment  management 

•  Country-specific  configuration 
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Programs  access  system  functions  using  software  interrupt  (INT)  instructions.  MS-DOS 
reserves  Interrupts  20H  through  3FH  for  this  purpose.  The  MS-DOS  interrupts  are 


Interrupt  Name 


20H 

21H 

22H 

23H 

24H 

25H 

26H 

27H 

28H-2EH 

2FH 

30H-3FH 


Terminate  Program 
MS-DOS  Function  Calls 
Terminate  Routine  Address 
Control-C  Handler  Address 
Critical  Error  Handler  Address 
Absolute  Disk  Read 
Absolute  Disk  Write 
Terminate  and  Stay  Resident 
Reserved 
Multiplex 
Reserved 


Interrupt  21H  is  the  main  source  of  MS-DOS  services.  The  Interrupt  21H  functions  are 
implemented  by  placing  a  function  number  in  the  AH  register,  placing  any  necessary 
parameters  in  other  registers,  and  issuing  an  INT  21H  instruction.  (MS-DOS  also  supports 
a  call  instruction  interface  for  CP/M  compatibility.  The  function  and  parameter  registers 
differ  from  the  interrupt  interface.  The  CP/M  interface  was  provided  in  MS-DOS  version  1.0 
solely  to  assist  in  movement  of  CP/M-based  applications  to  MS-DOS.  New  applications 
should  use  Interrupt  21H  functions  exclusively.) 

MS-DOS  version  2.0  introduced  a  mechanism  to  modify  the  operation  of  the  MS-DOS  BIOS 
and  kernel:  the  CONFIG.SYS  file.  CONFIG.SYS  is  a  text  file  containing  command  options 
that  modify  the  size  or  configuration  of  internal  MS-DOS  tables  and  cause  additional  de¬ 
vice  drivers  to  be  loaded.  The  file  is  read  when  MS-DOS  is  first  loaded  into  memory.  See 
USER  COMMANDS:  CONFIG.SYS. 

The  MS-DOS  shell 

The  shell,  or  command  interpreter,  is  the  first  program  started  by  MS-DOS  after  the 
MS-DOS  BIOS  and  kernel  have  been  loaded  and  initialized.  It  provides  the  interface 
between  the  kernel  and  the  user.  The  default  MS-DOS  shell,  COMMAND.COM,  is  a 
command-oriented  interface;  other  shells  may  be  menu-driven  or  screen-oriented. 

COMMAND.COM  is  a  replaceable  shell.  A  number  of  commercial  products  can  be  used 
as  COMMAND.COM  replacements,  or  a  programmer  can  develop  a  customized  shell.  The 
new  shell  program  is  installed  by  renaming  the  program  to  COMMAND.COM  or  by  using 
the  SHELL  command  in  CONFIG.SYS.  The  latter  method  is  preferred  because  it  allows 
initialization  parameters  to  be  passed  to  the  shell  program. 
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COMMAND.COM  can  execute  a  set  of  internal  (built-in)  commands,  load  and  execute 
programs,  or  interpret  batch  files.  Most  of  the  internal  commands  support  file  and  direc¬ 
tory  operations  and  manipulate  the  program  environment  segment  maintained  by 
COMMAND.COM.  The  programs  executed  by  COMMAND.COM  are  .COM  or  .EXE  files 
loaded  from  a  block  device.  The  batch  (.BAT)  files  supported  by  COMMAND.COM  pro¬ 
vide  a  limited  programming  language  and  are  therefore  useful  for  performing  small, 
frequently  used  series  of  MS-DOS  commands.  In  particular,  when  it  is  first  loaded  by 
MS-DOS,  COMMAND.COM  searches  for  the  batch  file  AUTOEXEC.BAT  and  interprets  it,  if 
found,  before  taking  any  other  action.  COMMAND.COM  also  provides  default  terminate, 
Control-C  and  critical  error  handlers  whose  addresses  are  stored  in  the  vectors  for  Inter¬ 
rupts  22H,  23H,  and  24H.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT: 
Customizing  ms-dos:  Exception  Handlers. 

COMMAND.COM’s  split  personality 

COMMAND.COM  is  a  conventional  .COM  application  with  a  slight  twist.  Ordinarily,  a 
.COM  program  is  loaded  into  a  single  memory  segment.  COMMAND.COM  starts  this  way 
but  then  copies  the  nonresident  portion  of  itself  into  high  memory  and  keeps  the  resident 
portion  in  low  memory.  The  memory  above  the  resident  portion  is  released  to  MS-DOS. 

The  effect  of  this  split  is  not  apparent  until  after  an  executed  program  has  terminated 
and  the  resident  portion  of  COMMAND.COM  regains  control  of  the  system.  The  resident 
portion  then  computes  a  checksum  on  the  area  in  high  memory  where  the  nonresident 
portion  should  be,  to  determine  whether  it  has  been  overwritten.  If  the  checksum  matches 
a  stored  value,  the  nonresident  portion  is  assumed  to  be  intact;  otherwise,  a  copy  of  the 
nonresident  portion  is  reloaded  from  disk  and  COMMAND.COM  continues  its  normal 
operation. 

This  “split  personality”  exists  because  MS-DOS  was  originally  designed  for  systems  with  a 
limited  amount  of  RAM.  The  nonresident  portion  of  COMMAND.COM,  which  contains  the 
built-in  commands  and  batch-file-processing  routines  that  are  not  essential  to  regaining 
control  and  reloading  itself,  is  much  larger  than  the  resident  portion,  which  is  responsible 
for  these  tasks.  Thus,  permitting  the  nonresident  portion  to  be  overwritten  frees  additional 
RAM  and  allows  larger  application  programs  to  be  run. 

Command  execution 

COMMAND.COM  interprets  commands  by  first  checking  to  see  if  the  specified  command 
matches  the  name  of  an  internal  command.  If  so,  it  executes  the  command;  otherwise,  it 
searches  for  a  .COM,  .EXE,  or  .BAT  file  (in  that  order)  with  the  specified  name.  If  a  .COM 
or  .EXE  program  is  found,  COMMAND.COM  uses  the  MS-DOS  EXEC  function  (Interrupt 
21H  Function  4BH)  to  load  and  execute  it;  COMMAND.COM  itself  interprets  .BAT  files. 

If  no  file  is  found,  the  message  Bad  command  or  file  name  is  displayed. 

Although  a  command  is  usually  simply  a  filename  without  the  extension,  MS-DOS  versions 
3.0  and  later  allow  a  command  name  to  be  preceded  by  a  full  pathname.  If  a  path  is  not 
explicitly  specified,  the  COMMAND.COM  search  mechanism  uses  the  contents  of  the 
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PATH  environment  variable,  which  can  contain  a  list  of  paths  to  be  searched  for  com¬ 
mands.  The  search  starts  with  the  current  directory  and  proceeds  through  the  directories 
specified  by  PATH  until  a  file  is  found  or  the  list  is  exhausted.  For  example,  the  PATH 
specification 

PATH  C:\BIN;D:\BIN;E:\ 

causes  COMMAND.COM  to  search  the  current  directory,  then  CABIN,  then  DABIN,  and 
finally  the  root  directory  of  drive  E.  COMMAND.COM  searches  each  directory  for  a  match¬ 
ing  .COM,  .EXE,  or  .BAT  file,  in  that  order,  before  moving  to  the  next  directory. 

MS-DOS  environments 

Version  2.0  introduced  the  concept  of  environments  to  MS-DOS.  An  environment  is  a 
paragraph-aligned  memory  segment  containing  a  concatenated  set  of  zero-terminated 
(ASCIIZ)  variable-length  strings  of  the  form 

variable^valt4e 

that  provide  such  information  as  the  current  search  path  used  by  COMMAND.COM  to  find 
executable  files,  the  location  of  COMMAND.COM  itself,  and  the  format  of  the  user  prompt. 
The  end  of  the  set  of  strings  is  marked  by  a  null  string — that  is,  a  single  zero  byte.  A 
specific  environment  is  associated  with  each  program  in  memory  through  a  pointer  con¬ 
tained  at  offset  2CH  in  the  256-byte  program  segment  prefix  (PSP).  The  maximum  size  of 
an  environment  is  32  KB;  the  default  size  is  160  bytes. 

If  a  program  uses  the  EXEC  function  to  load  and  execute  another  program,  the  contents  of 
the  new  program’s  environment  are  provided  to  MS-DOS  by  the  initiating  program — one 
of  the  parameters  passed  to  the  MS-DOS  EXEC  function  is  a  pointer  to  the  new  program’s 
environment.  The  default  environment  provided  to  the  new  program  is  a  copy  of  the 
initiating  program’s  environment. 

A  program  that  uses  the  EXEC  function  to  load  and  execute  another  program  will  not 
itself  have  access  to  the  new  program’s  environment,  because  MS-DOS  provides  a  pointer 
to  this  environment  only  to  the  new  program.  Any  changes  made  to  the  new  program’s  en¬ 
vironment  during  program  execution  are  invisible  to  the  initiating  program  because  a 
child  program’s  environment  is  always  discarded  when  the  child  program  terminates. 

The  system’s  master  environment  is  normally  associated  with  the  shell  COMMAND.COM. 
COMMAND.COM  creates  this  set  of  environment  strings  within  itself  from  the  contents 
of  the  CONFIG.SYS  and  AUTOEXEC.BAT  files,  using  the  SET,  PATH,  and  PROMPT  com¬ 
mands.  See  USER  COMMANDS:  autoexec.bat;  config.sys.  In  MS-DOS  version  3.2,  the 
initial  size  of  COMMAND. COM’s  environment  can  be  controlled  by  loading 
COMMAND.COM  with  the  /E  parameter,  using  the  SHELL  directive  in  CONFIG.SYS. 

For  example,  placing  the  line 

SHELL=COMMAND . COM  /E:2048  /P 
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in  CONFIG.SYS  sets  the  initial  size  of  COMMAND. COM’s  environment  to  2  KB.  (The  /P 
option  prevents  COMMAND.COM  from  terminating,  thus  causing  it  to  remain  in  memory 
until  the  system  is  turned  off  or  restarted.) 

The  SET  command  is  used  to  display  or  change  the  COMMAND.COM  environment  con¬ 
tents.  SET  with  no  parameters  displays  the  list  of  all  the  environment  strings  in  the  envi¬ 
ronment.  A  typical  listing  might  show  the  following  settings: 

COMSPEC=A : \ COMMAND . COM 
PATH=C:\;A:\;B:\ 

PROMPT=$p  $d  $t$_$n$g 
TMP=C;\TEMP 

The  following  is  a  dump  of  the  environment  segment  containing  the  previous  environment 
example: 


0  12  3 
0000  43  4F  4D  53 
0010  4E  44  2E  43 
0020  41  3A  5C  3B 
0030  70  20  20  24 
0040  54  4D  50  3D 


4  5  6  7  8  9 

50  45  43  3D-41  3A 

4F  4D  00  50-41  54 

42  3A  5C  00-50  52 

64  20  20  24-74  24 

43  3A  5C  54-45  4D 


A  B  C  D  E  F 
5C  43  4F  4D  4D  41 
48  3D  43  3A  5C  3B 
4F  4D  50  54  3D  24 
5F  24  6E  24  67  00 
50  00  00  00  00  00 


COMSPEC=A:\ COMMA 
ND.COM.PATH=C:\; 
A:\;B:\.PROMPT=$ 
p  $d  $t$_$n$g. 
TMP=C:\TEMP . 


A  SET  command  that  specifies  a  variable  but  does  not  specify  a  value  for  it  deletes  the  vari¬ 
able  from  the  environment. 


A  program  can  ignore  the  contents  of  its  environment;  however,  use  of  the  environment 
can  add  a  great  deal  to  the  flexibility  and  configurability  of  batch  files  and  application 
programs. 

Batch  files 


Batch  files  are  text  files  with  a  .BAT  extension  that  contain  MS-DOS  user  and  batch  com¬ 
mands.  Each  line  in  the  file  is  limited  to  128  bytes.  See  USER  COMMANDS:  batch.  Batch 
files  can  be  created  using  most  text  editors,  including  EDLIN,  and  short  batch  files  can 
even  be  created  using  the  COPY  command: 


OCOPY  CON  SAMPLE.BAT  <Enter> 

The  CON  device  is  the  system  console;  text  entered  from  the  keyboard  is  echoed  on  the 
screen  as  it  is  typed.  The  copy  operation  is  terminated  by  pressing  Ctrl-2  (or  the  F6  key  on 
IBM-compatible  machines),  followed  by  the  Enter  key. 

Batch  files  are  interpreted  by  COMMAND.COM  one  line  at  a  time.  In  addition  to  the  stan¬ 
dard  MS-DOS  commands,  COMMAND. COM’s  batch-file  interpreter  supports  a  number  of 
special  batch  commands: 


Command  Meaning 

ECHO  *  Display  a  message. 

FOR  *  Execute  a  command  for  a  list  of  files. 


(more) 
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Command 

Meaning 

GOTO* 

Transfer  control  to  another  point. 

IF* 

Conditionally  execute  a  command. 

PAUSE 

Wait  for  any  key  to  be  pressed. 

REM 

Insert  comment  line. 

SHIFT* 

Access  more  than  10  parameters. 

*  MS-DOS  versions  2.0  and  later 


Execution  of  a  batch  file  can  be  terminated  before  completion  by  pressing  Ctrl-C  or 
Ctrl-Break,  causing  COMMAND.COM  to  display  the  prompt 

Terminate  batch  job?  (Y/N) 

I/O  redirection 

I/O  redirection  was  introduced  with  MS-DOS  version  2.0.  The  redirection  facility  is  imple¬ 
mented  within  COMMAND.COM  using  the  Interrupt  21H  system  functions  Duplicate  File 
Handle  (45H)  and  Force  Duplicate  File  Handle  (46H).  C0MMAND.COM  uses  these  func¬ 
tions  to  provide  both  redirection  at  the  command  level  and  a  UNDC/XENEX-like  pipe 
facility. 

Redirection  is  transparent  to  application  programs,  but  to  take  advantage  of  redirection,  an 
application  program  must  make  use  of  the  standard  input  and  output  file  handles.  The  in¬ 
put  and  output  of  application  programs  that  directly  access  the  screen  or  keyboard  or  use 
ROM  BIOS  functions  cannot  be  redirected. 

Redirection  is  specified  in  the  command  line  by  prefixing  file  or  device  names  with  the 
special  characters  >, »,  and  <.  Standard  output  (default  =  CON)  is  redirected  using  >  and 
»  followed  by  the  name  of  a  file  or  character  device.  The  former  character  creates  a  new 
file  (or  overwrites  an  existing  file  with  the  same  name);  the  latter  appends  text  to  an  exist¬ 
ing  file  (or  creates  the  file  if  it  does  not  exist).  Standard  input  (default  =  CON)  is  redirected 
with  the  <  character  followed  by  the  name  of  a  file  or  character  device.  See  also  PRO¬ 
GRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Writing  MS-DOS 
Filters. 

The  redirection  facility  can  also  be  used  to  pass  information  from  one  program  to  an¬ 
other  through  a  “pipe.”  A  pipe  in  MS-DOS  is  a  special  file  created  by  COMMAND.COM. 
COMMAND.COM  redirects  the  output  of  one  program  into  this  file  and  then  redirects  this 
file  as  the  input  to  the  next  program.  The  pipe  symbol,  a  vertical  bar  (!),  separates  the  pro¬ 
gram  names.  Multiple  program  names  can  be  piped  together  in  the  same  command  line: 

ODIR  *.♦  1  SORT  !  MORE  <Enter> 

This  command  is  equivalent  to 

ODIR  *.*  >  PIPED  <Enter> 

OSORT  <  PIPED  >  PIPE1  <Enter> 

OMORE  <  PIPE1  <Enter> 
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The  concept  of  pipes  came  from  UNIX/XENIX,  but  UNEX/XENIX  is  a  multitasking  oper¬ 
ating  system  that  actually  runs  the  programs  simultaneously.  UNIX/XENIX  uses  memory 
buffers  to  connect  the  programs,  whereas  MS-DOS  loads  one  program  at  a  time  and  passes 
information  through  a  disk  file. 


Loading  MS-DOS 

Getting  MS-DOS  up  to  the  standard  A>  prompt  is  a  complex  process  with  a  number  of 
variations.  This  section  discusses  the  complete  process  normally  associated  with  MS-DOS 
versions  2.0  and  later.  (MS-DOS  versions  1.x  use  the  same  general  steps  but  lack  support  for 
various  system  tables  and  installable  device  drivers.) 

MS-DOS  is  loaded  as  a  result  of  either  a  “cold  boot”  or  a  “warm  boot.”  On  IBM-compatible 
machines,  a  cold  boot  is  performed  when  the  computer  is  first  turned  on  or  when  a  hard¬ 
ware  reset  occurs.  A  cold  boot  usually  performs  a  power-on  self  test  (POST)  and  deter¬ 
mines  the  amount  of  memory  available,  as  well  as  which  peripheral  adapters  are  installed. 
The  POST  is  ordinarily  reserved  for  a  cold  boot  because  it  takes  a  noticeable  amount  of 
time.  For  example,  an  IBM-compatible  ROM  BIOS  tests  all  conventional  and  extended 
RAM  (RAM  above  1  MB  on  an  80286-based  or  80386-based  machine),  a  procedure  that 
can  take  tens  of  seconds.  A  warm  boot,  initiated  by  simultaneously  pressing  the  Ctrl,  Alt, 
and  Del  keys,  bypasses  these  hardware  checks  and  begins  by  checking  for  a  bootable  disk. 

A  bootable  disk  normally  contains  a  small  loader  program  that  loads  MS-DOS  from  the 
same  disk.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Structure  of  ms-dos: 
MS-DOS  Storage  Devices.  The  body  of  MS-DOS  is  contained  in  two  files:  lO.SYS  and 
MSDOS.SYS  (IBMBIO.COM  and  IBMDOS.COM  with  PC-DOS).  lO.SYS  contains  the 
Microsoft  system  initialization  module,  SYSINIT,  which  configures  MS-DOS  using  either 
default  values  or  the  specifications  in  the  CONFIG.SYS  file,  if  one  exists,  and  then  starts  up 
the  shell  program  (usually  COMMAND.COM,  the  default).  COMMAND.COM  checks  for  an 
AUTOEXEC.BAT  file  and  interprets  the  file  if  found.  (Other  shells  might  not  support  such 
batch  files.)  Finally,  COMMAND.COM  prompts  the  user  for  a  command.  (The  standard 
MS-DOS  prompt  is  A>  if  the  system  was  booted  from  a  floppy  disk  and  C>  if  the  system 
was  booted  from  a  fixed  disk.)  Each  of  these  steps  is  discussed  in  detail  below. 

The  ROM  BIOS,  POST,  and  bootstrapping 

All  8086/8088-compatible  microprocessors  begin  execution  with  the  CS:IP  set  to 
FFFF:OOOOH,  which  typically  contains  a  jump  instruction  to  a  destination  in  the  ROM  BIOS 
that  contains  the  initialization  code  for  the  machine.  (This  has  nothing  to  do  with  MS-DOS;^ 
it  is  a  feature  of  the  Intel  microprocessors.)  On  IBM-compatible  machines,  the  ROM  BIOS  ^ 
occupies  the  address  space  from  FOOO.OOOOH  to  this  jump  instruction.  Figure  2-1  shows  the 
location  of  the  ROM  BIOS  within  the  1  MB  address  space.  Supplementary  ROM  support 
can  be  placed  before  (at  lower  addresses  than)  the  ROM  BIOS. 

All  interrupts  are  disabled  when  the  microprocessor  starts  execution  and  it  is  up  to  the 
initialization  routine  to  set  up  the  interrupt  vectors  at  the  base  of  memory. 
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Figure  2-1.  Memory  layout  at  startup. 


The  initialization  routine  in  the  ROM  BIOS — the  POST  procedure — typically  deter¬ 
mines  what  devices  are  installed  and  operational  and  checks  conventional  memory  (the 
first  1  MB)  and,  for  80286-based  or  80386-based  machines,  extended  memory  (above  1 
MB).  The  devices  are  tested,  where  possible,  and  any  problems  are  reported  using  a  series 
of  beeps  and  display  messages  on  the  screen. 

When  the  machine  is  found  to  be  operational,  the  ROM  BIOS  sets  it  up  for  normal  opera¬ 
tion.  First,  it  initializes  the  interrupt  vector  table  at  the  beginning  of  memory  and  any  inter¬ 
rupt  controllers  that  reference  the  table.  The  interrupt  vector  table  area  is  located  from 
OOOOiOOOOH  to  0000:03FFH.  On  IBM-compatible  machines,  some  of  the  subsequent  mem¬ 
ory  (starting  at  address  0000:0400H)  is  used  for  table  storage  by  various  ROM  BIOS  rou¬ 
tines  (Figure  2-2).  The  beginning  load  address  for  the  MS-DOS  system  files  is  usually  in 
the  range  0000:0600H  to  0000:0800H. 

Next,  the  ROM  BIOS  sets  up  any  necessary  hardware  interfaces,  such  as  direct  memory 
access  (DMA)  controllers,  serial  ports,  and  the  like.  Some  hardware  setup  may  be  done 
before  the  interrupt  vector  table  area  is  set  up.  For  example,  the  IBM  PC  DMA  controller 
also  provides  refresh  for  the  dynamic  RAM  chips  and  RAM  cannot  be  used  until  the 
refresh  DMA  is  runniftg;  therefore,  the  DMA  must  be  set  up  first. 

Some  ROM  BIOS  implementations  also  check  to  see  if  additional  ROM  BIOSs  are  installed 
by  scanning  the  memory  from  AOOOiOOOOH  to  F000:0000H  for  a  particular  sequence  of  sig¬ 
nature  bytes.  If  additional  ROM  BIOSs  are  found,  their  initialization  routines  are  called  to 
initialize  the  associated  devices.  Examples  of  additional  ROMs  for  the  IBM  PC  family  are 
the  PC/XT’s  fixed-disk  ROM  BIOS  and  the  EGA  ROM  BIOS. 

The  ROM  BIOS  now  starts  the  bootstrap  procedure  by  executing  the  ROM  loader  routine. 
On  the  IBM  PC,  this  routine  checks  the  first  floppy-disk  drive  to  see  if  there  is  a  bootable 
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Figure  2-2.  The  interrupt  vector  table  and  the  ROM  BIOS  table. 


disk  in  it.  If  there  is  not,  the  routine  then  invokes  the  ROM  associated  with  another  boot¬ 
able  device  to  see  if  that  device  contains  a  bootable  disk.  This  procedure  is  repeated  until 
a  bootable  disk  is  found  or  until  all  bootable  devices  have  been  checked  without  success, 
in  which  case  ROM  BASIC  is  enabled. 

Bootable  devices  can  be  detected  by  a  number  of  proprietary  means.  The  IBM  PC  ROM 
BIOS  reads  the  first  sector  on  the  disk  into  RAM  (Figure  2-3)  and  checks  for  an  8086-family 
short  or  long  jump  at  the  beginning  of  the  sector  and  for  AA55H  in  the  last  word  of  the  sec¬ 
tor.  This  signature  indicates  that  the  sector  contains  the  operating-system  loader.  Data 
disks — those  disks  not  set  up  with  the  MS-DOS  system  files — usually  cause  the  ROM 
loader  routine  to  display  a  message  indicating  that  the  disk  is  not  a  bootable  system  disk. 
The  customary  recovery  procedure  is  to  display  a  message  asking  the  user  to  insert 
another  disk  (with  the  operating  system  files  on  it)  and  press  a  key  to  try  the  load  opera¬ 
tion  again.  The  ROM  loader  routine  is  then  typically  reexecuted  from  the  beginning  so 
that  it  can  repeat  its  normal  search  procedure. 

When  it  finds  a  bootable  device,  the  ROM  loader  routine  loads  the  operating-system  loader 
and  transfers  control  to  it.  The  operating-system  loader  then  uses  the  ROM  BIOS  services 
through  the  interrupt  table  to  load  the  next  part  of  the  operating  system  into  low  memory. 

Before  it  can  proceed,  the  operating-system  loader  must  know  something  about  the  con¬ 
figuration  of  the  system  boot  disk  (Figure  2-4).  MS-DOS-compatible  disks  contain  a  data 
structure  that  contains  this  information.  This  structure,  known  as  the  BIOS  parameter 
block  (BPB),  is  located  in  the  same  sector  as  the  operating-system  loader.  From  the  con¬ 
tents  of  the  BPB,  the  operating-system  loader  calculates  the  location  of  the  root  directory 
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Figure  2-3 ‘  A  loaded  boot  sector. 
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Figure  2-4.  Boot-disk  configuration. 


Section  II:  Programming  in  the  MS-DOS  Environment 


71 


Part  A:  Structure  of  MS-DOS 


for  the  boot  disk  so  that  it  can  verify  that  the  first  two  entries  in  the  root  directory  are 
lO.SYS  and  MSDOS.SYS.  For  versions  of  MS-DOS  through  3.2,  these  files  must  also  be  the 
first  two  files  in  the  file  data  area,  and  they  must  be  contiguous.  (The  operating-system 
loader  usually  does  not  check  the  file  allocation  table  [FAT]  to  see  if  lO.SYS  and 
MSDOS.SYS  are  actually  stored  in  contiguous  sectors.)  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Structure  of  ms-dos:  MS-DOS  Storage  Devices. 

Next,  the  operating-system  loader  reads  the  sectors  containing  lO.SYS  and  MSDOS.SYS 
into  contiguous  areas  of  memory  just  above  the  ROM  BIOS  tables  (Figure  2-5).  (An  alterna¬ 
tive  method  is  to  take  advantage  of  the  operating-system  loader’s  final  jump  to  the  entry 
point  in  lO.SYS  and  include  routines  in  lO.SYS  that  allow  it  to  load  MSDOS.SYS.) 

Finally,  assuming  the  file  was  loaded  without  any  errors,  the  operating-system  loader 
transfers  control  to  lO.SYS,  passing  the  identity  of  the  boot  device.  The  operating-system 
loader  is  no  longer  needed  and  its  RAM  is  made  available  for  other  purposes. 
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Figure  2-5.  lO.SYS  and  MSDOS.SYS  loaded. 
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MS-DOS  system  initialization  (SYSINIT) 

MS-DOS  system  initialization  begins  after  the  operating-system  loader  has  loaded  lO.SYS 
and  MSDOS.SYS  and  transferred  control  to  the  beginning  of  lO.SYS.  To  this  point,  there 
has  been  no  standard  loading  procedure  imposed  by  MS-DOS,  although  the  IBM  PC  load¬ 
ing  procedure  outlined  here  has  become  the  de  facto  standard  for  most  MS-DOS  machines. 
When  control  is  transferred  to  lO.SYS,  however,  MS-DOS  imposes  its  standards. 

The  lO.SYS  file  is  divided  into  three  modules: 

•  The  resident  device  drivers 

•  The  basic  MS-DOS  BIOS  initialization  module 

•  The  MS-DOS  system  initialization  module,  SYSINIT 

The  two  initialization  modules  are  usually  discarded  as  soon  as  MS-DOS  is  completely 
initialized  and  the  shell  program  is  running;  the  resident  device  drivers  remain  in  memory 
while  MS-DOS  is  running  and  are  therefore  placed  in  the  first  part  of  the  lO.SYS  file, 
before  the  initialization  modules. 

The  MS-DOS  BIOS  initialization  module  ordinarily  displays  a  sign-on  message  and  the 
copyright  notice  for  the  OEM  that  created  lO.SYS.  On  IBM-compatible  machines,  it  then 
examines  entries  in  the  interrupt  table  to  determine  what  devices  were  found  by  the  ROM 
BIOS  at  POST  time  and  adjusts  the  list  of  resident  device  drivers  accordingly.  This  adjust¬ 
ment  usually  entails  removing  those  drivers  that  have  no  corresponding  installed  hard¬ 
ware,  The  initialization  routine  may  also  modify  internal  tables  within  the  device  drivers. 
The  device  driver  initialization  routines  will  be  called  later  by  SYSINIT,  so  the  MS-DOS 
BIOS  initialization  routine  is  now  essentially  finished  and  control  is  transferred  to  the 
SYSINIT  module. 

SYSINIT  locates  the  top  of  RAM  and  copies  itself  there.  It  then  transfers  control  to  the  copy 
and  the  copy  proceeds  with  system  initialization.  The  first  step  is  to  move  MSDOS.SYS, 
which  contains  the  MS-DOS  kernel,  to  a  position  immediately  following  the  end  of  the 
resident  portion  of  lO.SYS,  which  contains  the  resident  device  drivers.  This  move  over¬ 
writes  the  original  copy  of  SYSINIT  and  usually  all  of  the  MS-DOS  BIOS  initialization  rou¬ 
tine,  which  are  no  longer  needed.  The  resulting  memory  layout  is  shown  in  Figure  2-6. 

SYSINIT  then  calls  the  initialization  routine  in  the  newly  relocated  MS-DOS  kernel.  This 
routine  performs  the  internal  setup  for  the  kernel,  including  putting  the  appropriate  values 
into  the  vectors  for  Interrupts  20H  through  3FH. 

The  MS-DOS  kernel  initialization  routine  then  calls  the  initialization  function  of  each 
resident  device  driver  to  set  up  vectors  for  any  external  hardware  interrupts  used  by  the 
device.  Each  block-device  driver  returns  a  pointer  to  a  BPB  for  each  drive  that  it  supports; 
these  BPBs  are  inspected  by  SYSINIT  to  find  the  largest  sector  size  used  by  any  of  the 
drivers.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Structure  of  ms-dos: 
MS-DOS  Storage  Devices.  The  kernel  initialization  routine  then  allocates  a  sector  buffer  the 
size  of  the  largest  sector  found  and  places  the  NUL  device  driver  at  the  head  of  the  device 
driver  list. 


Section  II:  Programming  in  the  MS-DOS  Environment  73 


Part  A:  Structure  of  MS-DOS 


ROM  BIOS 

Other  ROM  and  RAM 

SYSINIT 

Free  RAM 

MS-DOS  kernel 
(MSDOS.SYS) 

MS-DOS  BIOS 
(IO.SYS) 

ROM  BIOS  tables 

Interrupt  vectors 

FFFF:000FH(1  MB) 


F000:0000H 


Top  of  RAM 

(A000:0000H  for  ffiM  PC) 


Resident  device  drivers 

0000:0600H 

0000:0400H 

0000:OOOOH 


Figure  2-6.  SYSINIT  and  MSDOS.SYS  relocated. 


The  kernel  initialization  routine’s  final  operation  before  returning  to  SYSINIT  is  to  display 
the  MS-DOS  copyright  message.  The  loading  of  the  system  portion  of  MS-DOS  is  now  com¬ 
plete  and  SYSINIT  can  use  any  MS-DOS  function  in  conjunction  with  the  resident  set  of 
device  drivers. 

SYSINIT  next  attempts  to  open  the  CONFIG.SYS  file  in  the  root  directory  of  the  boot 
drive.  If  the  file  does  not  exist,  SYSINIT  uses  the  default  system  parameters;  if  the  file  is 
opened,  SYSINIT  reads  the  entire  file  into  high  memory  and  converts  all  characters  to 
uppercase.  The  file  contents  are  then  processed  to  determine  such  settings  as  the  number 
of  disk  buffers,  the  number  of  entries  in  the  file  tables,  and  the  number  of  entries  in  the 
drive  translation  table  (depending  on  the  specific  commands  in  the  file),  and  these  struc¬ 
tures  are  allocated  following  the  MS-DOS  kernel  (Figure  2-7). 

Then  SYSINIT  processes  the  CONFIG.SYS  text  sequentially  to  determine  what  installable 
device  drivers  are  to  be  implemented  and  loads  the  installable  device  driver  files  into 
memory  after  the  system  disk  buffers  and  the  file  and  drive  tables.  Installable  device  driver 
files  can  be  located  in  any  directory  on  any  drive  whose  driver  has  already  been  loaded. 
Each  installable  device  driver  initialization  function  is  called  after  the  device  driver  file  is 
loaded  into  memory.  The  initialization  procedure  is  the  same  as  for  resident  device  drivers, 
except  that  SYSINIT  uses  an  address  returned  by  the  device  driver  itself  to  determine 
where  the  next  device  driver  is  to  be  placed.  See  PROGRAMMING  IN  THE  MS-DOS  ENVI¬ 
RONMENT:  Customizing  ms-dos:  Installable  Device  Drivers. 
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Figure  2-  7.  Tables  allocated  and  installable  device  drivers  loaded. 


Like  resident  device  drivers,  installable  device  drivers  can  be  discarded  by  SYSINIT  if  the 
device  driver  initialization  routine  determines  that  a  device  is  inoperative  or  nonexistent. 
A  discarded  device  driver  is  not  included  in  the  list  of  device  drivers.  Installable  character- 
device  drivers  supersede  resident  character-device  drivers  with  the  same  name;  installable 
block-device  drivers  cannot  supersede  resident  block-drivers  and  are  assigned  drive  letters 
following  those  of  the  resident  block-device  drivers. 
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SYSINIT  now  closes  all  open  files  and  then  opens  the  three  character  devices  CON,  PRN, 
and  AUX.  The  console  (CON)  is  used  as  standard  input,  standard  output,  and  standard 
error;  the  standard  printer  port  is  PRN  (which  defaults  to  LPTl);  the  standard  auxiliary  port 
is  AUX  (which  defaults  to  COMl).  Installable  device  drivers  with  these  names  will  replace 
any  resident  versions. 

Starting  the  shell 

SYSINIT’s  last  function  is  to  load  and  execute  the  shell  program  by  using  the  MS-DOS 
EXEC  function.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming 
FOR  MS-DOS:  The  MS-DOS  EXEC  Function.  The  SHELL  statement  in  CONFIG.SYS  specifies 
both  the  name  of  the  shell  program  and  its  initial  parameters;  the  default  MS-DOS  shell  is 
COMMAND.COM.  The  shell  program  is  loaded  at  the  start  of  free  memory  after  the 
installable  device  drivers  or  after  the  last  internal  MS-DOS  file  control  block  if  there  are 
no  installable  device  drivers  (Figure  2-8). 

COMMAND.COM 

COMMAND.COM  consists  of  three  parts: 

•  A  resident  portion 

•  An  initialization  module 

•  A  transient  portion 

The  resident  portion  contains  support  for  termination  of  programs  started  by 
COMMAND.COM  and  presents  critical-error  messages.  It  is  also  responsible  for  re¬ 
loading  the  transient  portion  when  necessary. 

The  initialization  module  is  called  once  by  the  resident  portion.  First,  it  moves  the  tran¬ 
sient  portion  to  high  memory,  (Compare  Figures  2-8  and  2-9.)  Then  it  processes  the 
parameters  specified  in  the  SHELL  command  in  the  CONFIG.SYS  file,  if  any.  See  USER 
COMMANDS:  command.  Next,  it  processes  the  AUTOEXEC.BAT  file,  if  one  exists,  and 
finally,  it  transfers  control  back  to  the  resident  portion,  which  frees  the  space  used  by  the 
initialization  module  and  transient  portion.  The  relocated  transient  portion  then  displays 
the  MS-DOS  user  prompt  and  is  ready  to  accept  commands. 

The  transient  portion  gets  a  command  from  either  the  console  or  a  batch  file  and  executes 
it.  Commands  are  divided  into  three  categories: 

•  Internal  commands 

•  Batch  files 

•  External  commands 

Internal  commands  are  routines  contained  within  COMMAND.COM  and  include  opera¬ 
tions  like  COPY  or  ERASE.  Execution  of  an  internal  command  does  not  overwrite  the  tran¬ 
sient  portion.  Internal  commands  consist  of  a  keyword,  sometimes  followed  by  a  list  of 
command-specific  parameters. 
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Figure  2-8.  COMMAND.COM loaded. 
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Figure  2-9.  COMMAND.COM  after  relocation. 


Batch  files  are  text  files  that  contain  internal  commands,  external  commands,  batch-file 
directives,  and  nonexecutable  comments.  See  USER  COMMANDS:  batch. 

External  commands,  which  are  actually  executable  programs,  are  stored  in  separate 
files  with  .COM  and  .EXE  extensions  and  are  included  on  the  MS-DOS  distribution  disks. 
5^^  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Struc¬ 
ture  of  an  Application  Program.  These  programs  are  invoked  with  the  name  of  the  file 
without  the  extension.  (MS-DOS  versions  3.x  allow  the  complete  pathname  of  the  external 
command  to  be  specified.) 
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External  commands  are  loaded  by  COMMAND.COM  by  means  of  the  MS-DOS  EXEC  func¬ 
tion.  The  EXEC  function  loads  a  program  into  the  free  memory  area,  also  called  the  tran¬ 
sient  program  area  (TPA),  and  then  passes  it  control.  Control  returns  to  COMMAND.COM 
when  the  new  program  terminates.  Memory  used  by  the  program  is  released  unless  it  is  a 
terminate-and-stay-resident  (TSR)  program,  in  which  case  some  of  the  memory  is  retained 
for  the  resident  portion  of  the  program.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRON¬ 
MENT:  Customizing  ms-dos:  Terminate-and-Stay-Resident  Utilities. 

After  a  program  terminates,  the  resident  portion  of  COMMAND.COM  checks  to  see  if  the 
transient  portion  is  still  valid,  because  if  the  program  was  large,  it  may  have  overwritten 
the  transient  portion’s  memory  space.  The  validity  check  is  done  by  computing  a  check¬ 
sum  on  the  transient  portion  and  comparing  it  with  a  stored  value.  If  the  checksums  do 
not  match,  the  resident  portion  loads  a  new  copy  of  the  transient  portion  from  the 
COMMAND.COM  file. 

Just  as  COMMAND.COM  uses  the  EXEC  function  to  load  and  execute  a  program,  pro¬ 
grams  can  load  and  execute  other  programs  until  the  system  runs  out  of  memory.  Figure 
2-10  shows  a  typical  memory  configuration  for  multiple  applications  loaded  at  the  same 
time.  The  active  task — the  last  one  executed — ordinarily  has  complete  control  over  the 
system,  with  the  exception  of  the  hardware  interrupt.handlers,  which  gain  control 
whenever  a  hardware  interrupt  needs  to  be  serviced. 

MS-DOS  is  not  a  multitasking  operating  system,  so  although  several  programs  can  be  resi¬ 
dent  in  memory,  only  one  program  can  be  active  at  a  time.  The  stack-like  nature  of  the 
system  is  apparent  in  Figure  2-10.  The  top  program  is  the  active  one;  the  next  program 
down  will  continue  to  run  when  the  top  program  exits,  and  so  on  until  control  returns  to 
COMMAND.COM.  RAM-resident  programs  that  remain  in  memory  after  they  have  termi¬ 
nated  are  the  exception.  In  this  case,  a  program  lower  in  memory  than  another  program 
can  become  the  active  program,  although  the  one-active-process  limit  is  still  in  effect. 

A  custom  shell  program 

The  SHELL  directive  in  the  CONFIG.SYS  file  can  be  used  to  replace  the  system’s  default 
shell,  COMMAND, COM,  with  a  custom  shell.  Nearly  any  program  can  be  used  as  a  system 
shell  as  long  as  it  supplies  default  handlers  for  the  Control-C  and  critical  error  exceptions. 
For  example,  the  program  in  Figure  2-11  can  be  used  to  make  any  application  program 
appear  to  be  a  shell  program — if  the  application  program  terminates,  SHELL.COM 
restarts  it,  giving  the  appearance  that  the  application  program  is  the  shell  program. 

SHELL.COM  sets  up  the  segment  registers  for  operation  as  a  .COM  file  and  reduces  the 
program  segment  size  to  less  than  1  KB.  It  then  initializes  the  segment  values  in  the  param¬ 
eter  table  for  the  EXEC  function,  because  .COM  files  cannot  set  up  segment  values  within  a 
program.  The  Control-C  and  critical  error  interrupt  handler  vectors  are  set  to  the  address  of 
the  main  program  loop,  which  tries  to  load  the  new  shell  program.  SHELL.COM  prints  a 
message  if  the  EXEC  operation  fails.  The  loop  continues  forever  and.  SHELL.COM  will 
never  return  to  the  now-discarded  SYSINIT  that  started  it. 
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<-  FFFF:000FH(1  MB) 
FOOOiOOOOH 

Top  of  RAM 

(AOOOiOOOOH  for  ffiM  PC) 


<r-  Resident  device  drivers 

00{)0:0600H 
<—  0000:04(X)H 

OOOOrOOOOH 
Figure  2-10.  Multiple  programs  loaded. 
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SHELL. ASM  A  simple  program  to  run  an  application  as  an 
MS-DOS  shell  program.  The  program  name  and 
startup  parameters  must  be  adjusted  before 
SHELL  is  assembled. 

Written  by  William  Wong 

To  create  SHELL.COM: 


OMASM  SHELL; 

OLINK  SHELL; 

OEXE2BIN  SHELL.EXE  SHELL.COM 


stderr 

equ  2 

; 

standard  error 

cr 

equ  Odh 

; 

ASCII  carriage  return 

If 

equ  Oah 

; 

ASCII  linefeed 

cseg 

segment 

para  public  'CODE' 

;  — 

Set  up  DSj 

,  ES,  and 

SS:SP 

to  run  as  .COM 

assume 

cs:cseg 

start 

proc 

far 

mov 

ax,  cs 

;  set  up  segment  registers 

add 

ax, 1  Oh 

;  AX  =  segment  after  PSP 

mov 

ds,  ax 

mov 

ss,  ax 

;  set  up  stack  pointer 

mov 

sp, offset 

stk 

mov 

ax, offset 

shell 

push 

cs 

;  push  original  CS 

push 

ds 

;  push  segment  of  shell 

push 

ax 

;  push  offset  of  shell 

ret 

;  jump  to  shell 

start 

endp 

Main  program  running  as  .COM 


CS,  DS,  SS  =  cseg 

Original  CS  value  on  top  of  stack 


assume  cs : cseg, ds : cseg, ss : cseg 


equ 

( ( (offset  last)  - 

(offset  start))  +  10fh)/16 

proc 

near 

pop 

es 

;  ES  =  segment  to  shrink 

mov 

bx, seg_size 

;  BX  =  new  segment  size 

mov 

ah, 4 ah 

;  AH  =  modify  memory  block 

int 

21h 

;  free  excess  memory 

mov 

cmd_seg,  ds 

;  setup  segments  in 

mov 

fcb1_seg,  ds 

;  parameter  block  for  EXEC 

mov 

fcb2_seg, ds 

mov 

dx, offset  main. 

-loop 

mov 

ax,2523h 

;  AX  =  set  Control-C  handl( 

Figure  2-11.  A  simple  program  to  run  an  application  as  an  MS-DOS  shell. 


(more) 
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int 

21h 

set  handler  to  DS:DX 

mov 

dx, offset  main-loop 

mov 

ax,2524h 

AX  =  set  critical  error  handle 

int 

21h 

set  handler  to  DS:DX 

; 

Note:  DS  is  equal  to  CS 

main_loop : 

push 

ds  ; 

save  segment  registers 

push 

es 

mov 

cs : stk— seg,  ss  ; 

save  stack  pointer 

mov 

cs : stk_of f ,  sp 

mov 

dx, offset  pgm_name 

mov 

bx, offset  par_blk 

mov 

ax,4b00h  ; 

AX  =  EXEC/ run  program 

int 

21h 

carry  =  EXEC  failed 

mov 

ss, cs : stk—seg  ; 

restore  stack  pointer 

mov 

sp, cs : stk—of f 

pop 

es  ; 

restore  segment  registers 

pop 

ds 

jnc 

main-loop  ; 

loop  if  program  run 

mov 

dx, offset  load_msg 

mov 

CX, load_msg— length 

call 

print  / 

display  error  message 

mov 

ah,08h  ; 

AH  =  read  without  echo 

int 

21h 

wait  for  any  character 

jmp 

main-loop  ; 

execute  forever 

shell  endp 

/ 

;  —  Print  string  — 

/ 

;  DS:DX  =  address  of  string 

;  CX  =  size 

print  proc 

near 

mov 

ah,40h 

AH  =  write  to  file 

mov 

bx, stderr  ; 

BX  =  file  handle 

int 

21h 

print  string 

ret 

print  endp 

;  —  Message 

strings 

load_msg  db  cr 

,lf 

db  'Cannot  load  program.' 

,cr, If 

db  'Press  any  key  to  try 

again . ' ,  cr.  If 

load_msg_length  equ  $-loacL_msg 

;  —  Program 

data  area 

stk_seg  dw 

0 

stack  segment  pointer 

stk_off  dw 

0 

save  area  during  EXEC 

pgm_name  db 

'\NEWSHELL.COM',0 

;  any  program  will  do 

Figure  2-11.  Continued. 
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par_blk 

dw 

0 

dw 

offset 

cmd_line 

cmd_seg 

dw 

0 

dw 

offset 

fcbl 

fcb1_seg 

dw 

0 

dw 

offset 

fcb2 

fcb2_seg 

dw 

0 

cmd_line 

db 

0,  cr 

fcbl 

db 

0 

db 

1 1  dup 

(’  ') 

db 

25  dup 

(  0  ) 

fcb2 

db 

0 

db 

1 1  dup 

('  ') 

db 

25  dup 

(  0  ) 

dw 

200  dup 

'  (  0  ) 

stk 

dw 

0 

last 

equ 

$ 

cseg 

ends 

end 

start 

use  current  environment 

command-line  address 

fill  in  at  initialization 

default  FCB  #1 

fill  in  at  initialization 

default  FCB  #2 

fill  in  at  initialization 

actual  command  line 


;  program  stack  area 
;  last  address  used 


Figure  2-11.  Continued. 


SHELL.COM  is  very  short  and  not  too  smart.  It  needs  to  be  changed  and  rebuilt  if  the  name 
of  the  application  program  changes.  A  simple  extension  to  SHELL — call  it  XSHELL — 
would  be  to  place  the  name  of  the  application  program  and  any  parameters  in  the  com¬ 
mand  line.  XSHELL  would  then  have  to  parse  the  program  name  and  the  contents  of  the 
two  FCBs  needed  for  the  EXEC  function.  The  CONFIG.SYS  line  for  starting  this  shell 
would  be 

SHELL=XSHELL  \SHELL\DEMO.EXE  PARAM1  PARAM2  PARAM3 

SHELL.COM  does  not  set  up  a  new  environment  but  simply  uses  the  one  passed  to  it. 


William  Wong 
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Article  3 

MS-DOS  Storage  Devices 


Application  programs  access  data  on  MS-DOS  storage  devices  through  the  MS-DOS  file¬ 
system  support  that  is  part  of  the  MS-DOS  kernel.  The  MS-DOS  kernel  accesses  these 
storage  devices,  also  called  block  devices,  through  two  types  of  device  drivers:  resident 
block-device  drivers  contained  in  lO.SYS  and  installable  block-device  drivers  loaded 
from  individual  files  when  MS-DOS  is  loaded.  See  PROGRAMMING  IN  THE  MS-DOS 
ENVIRONMENT:  Structure  of  ms-dos:  The  Components  of  MS-DOS;  Customizing 
MS-DOS:  Installable  Device  Drivers. 

MS-DOS  can  handle  almost  any  medium,  recording  method,  or  other  variation  for  a  storage 
device  as  long  as  there  is  a  device  driver  for  it.  MS-DOS  needs  to  know  only  the  sector  size 
and  the  maximum  number  of  sectors  for  the  device;  the  appropriate  translation  between 
logical  sector  number  and  physical  location  is  made  by  the  device  driver.  Information 
about  the  number  of  heads,  tracks,  and  so  on  is  required  only  for  those  partitioning  pro¬ 
grams  that  allocate  logical  devices  along  these  boundaries.  See  Layout  of  a  Partition  below. 

The  floppy-disk  drive  is  perhaps  the  best-known  block  device,  followed  by  its  faster 
cousin,  the  fixed-disk  drive.  Other  MS-DOS  media  include  RAMdisks,  nonvolatile 
RAMdisks,  removable  hard  disks,  tape  drives,  and  CD  ROM  drives.  With  the  proper  device 
driver,  MS-DOS  can  place  a  file  system  on  any  of  these  devices  (except  read-only  media 
such  as  CD  ROM). 

This  article  discusses  the  structure  of  the  file  system  on  floppy  and  fixed  disks,  starting 
with  the  physical  layout  of  a  disk  and  then  moving  on  to  the  logical  layout  of  the  file  sys¬ 
tem.  The  scheme  examined  is  for  the  IBM  PC  fixed  disk. 


structure  of  an  MS-DOS  Disk 

The  structure  of  an  MS-DOS  disk  can  be  viewed  in  a  number  of  ways: 

•  Physical  device  layout 

•  Logical  device  layout 

•  Logical  block  layout 

•  MS-DOS  file  system 

The  physical  layout  of  a  disk  is  expressed  in  terms  of  sectors,  tracks,  and  heads.  The  logical 
device  layout,  also  expressed  in  terms  of  sectors,  tracks,  and  heads,  indicates  how  a  logical 
device  maps  onto  a  physical  device.  A  partitioned  physical  device  contains  multiple  logical 
devices;  a  physical  device  that  cannot  be  partitioned  contains  only  one.  Each  logical  device 
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has  a  logical  block  layout  used  by  MS-DOS  to  implement  a  file  system.  These  various 
views  of  an  MS-DOS  disk  are  discussed  below.  See  also  PROGRAMMING  IN  THE  MS-DOS 
ENVIRONMENT:  Programming  for  ms-dos:  File  and  Record  Management;  Disk  Directo¬ 
ries  and  Volume  Labels. 

Layout  of  a  physical  block  device 

The  two  major  block-device  implementations  are  solid-state  RAMdisks  and  rotating  mag¬ 
netic  media  such  as  floppy  or  fixed  disks.  Both  implementations  provide  a  fixed  amount  of 
storage  in  a  fixed  number  of  randomly  accessible  same-size  sectors. 

RAMdisks 

A  RAMdisk  is  a  block  device  that  has  sectors  mapped  sequentially  into  RAM.  Thus,  the 
RAMdisk  is  viewed  as  a  large  set  of  sequentially  numbered  sectors  whose  addresses  are 
computed  by  simply  multiplying  the  sector  number  by  the  sector  size  and  adding  the  base 
address  of  the  RAMdisk  sector  buffer.  Access  is  fast  and  efficient  and  the  access  time  to  any 
sector  is  fixed,  making  the  RAMdisk  the  fastest  block  device  available.  However,  there  are 
significant  drawbacks  to  RAMdisks.  First,  they  are  volatile;  their  contents  are  irretrievably 
lost  when  the  computer’s  power  is  turned  off  (although  a  special  implementation  of  the 
RAMdisk  known  as  a  nonvolatile  RAMdisk  includes  a  battery  backup  system  that  ensures 
that  its  contents  are  not  lost  when  the  computer’s  power  is  turned  off).  Second,  they  are 
usually  not  portable. 

Physical  disks 

Floppy-disk  and  fixed-disk  systems,  on  the  other  hand,  store  information  on  revolving 
platters  coated  with  a  special  magnetic  material.  The  disk  is  rotated  in  the  drive  at  high 
speeds — approximately  300  revolutions  per  minute  (rpm)  for  floppy  disks  and  3600  rpm 
for  fixed  disks.  (The  term  “fixed”  refers  to  the  fact  that  the  medium  is  built  permanently 
into  the  drive,  not  to  the  motion  of  the  medium.)  Fixed  disks  are  also  referred  to  as  “hard” 
disks,  because  the  disk  itself  is  usually  made  from  a  rigid  material  such  as  metal  or  glass; 
floppy  disks  are  usually  made  from  a  flexible  material  such  as  plastic. 

A  transducer  element  called  the  read/write  head  is  used  to  read  and  write  tiny  magnetic 
regions  on  the  rotating  magnetic  medium.  The  regions  act  like  small  bar  magnets  with 
north  and  south  poles.  The  magnetic  regions  of  the  medium  can  be  logically  oriented 
toward  one  or  the  other  of  these  poles — orientation  toward  one  pole  is  interpreted  as  a 
specific  binary  state  (1  or  0)  and  orientation  toward  the  other  pole  is  interpreted  as  the 
opposite  binary  state.  A  change  in  the  direction  of  orientation  (and  hence  a  change  in  the 
binary  value)  between  two  adjacent  regions  is  called  a  flux  reversal,  and  the  density  of  a 
particular  disk  implementation  can  be  measured  by  the  number  of  regions  per  inch  reli¬ 
ably  capable  of  flux  reversal.  Higher  densities  of  these  regions  yield  higher-capacity  disks. 
The  flux  density  of  a  particular  system  depends  on  the  drive  mechanics,  the  characteris¬ 
tics  of  the  read/write  head,  and  the  magnetic  properties  of  the  medium. 

The  read/write  head  can  encode  digital  information  on  a  disk  using  a  number  of  recording 
techniques,  including  frequency  modulation  (FM),  modified  frequency  modulation  (MFM), 
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run  length  limited  (RLL)  encoding,  and  advanced  run  length  limited  (ARLL)  encoding. 
Each  technique  offers  double  the  data  encoding  density  of  the  previous  one.  The  associ¬ 
ated  control  logic  is  more  complex  for  the  denser  techniques. 

Tracks 

A  read/write  head  reads  data  from  or  writes  data  to  a  thin  section  of  the  disk  called  a 
track,  which  is  laid  out  in  a  circular  fashion  around  the  disk  (Figure  3-1).  Standard  5.25- 
inch  floppy  disks  contain  either  40  (0-39)  or  80  (0-79)  tracks  per  side.  Like-numbered 
tracks  on  either  side  of  a  double-sided  disk  are  distinguished  by  the  number  of  the  read/ 
write  head  used  to  access  the  track.  For  example,  track  1  on  the  top  of  the  disk  is  identified 
as  head  0,  track  1;  track  1  on  the  bottom  of  the  disk  is  identified  as  head  1,  track  1. 

Tracks  can  be  either  spirals,  as  on  a  phonograph  record,  or  concentric  rings.  Computer 
media  usually  use  one  of  two  types  of  concentric  rings.  The  first  type  keeps  the  same  num¬ 
ber  of  sectors  on  each  track  isee  Sectors  below)  and  is  rotated  at  a  constant  angular  veloc¬ 
ity  (CAV).  The  second  type  maintains  the  same  recording  density  across  the  entire  surface 
of  the  disk,  so  a  track  near  the  center  of  a  disk  contains  fewer  sectors  than  a  track  near  the 
perimeter.  This  latter  type  of  disk  is  rotated  at  different  speeds  to  keep  the  medium  under 
the  magnetic  head  moving  at  a  constant  linear  velocity  (CLV). 


Sector 


Figure  3-1  ^  The  physical  layout  of  a  CAV  9-sector,  5. 25-inch  floppy  disk. 

Most  MS-DOS  computers  use  CAV  disks,  although  a  CLV  disk  can  store  more  sectors  using 
the  same  type  of  medium.  This  difference  in  storage  capacity  occurs  because  the  limiting 
factor  is  the  flux  density  of  the  medium  and  a  CAV  disk  must  maintain  the  same  number 
of  magnetic  flux  regions  per  sector  on  the  interior  of  the  disk  as  at  the  perimeter.  Thus, 
the  sectors  on  or  near  the  perimeter  do  not  use  the  full  capability  of  the  medium  and  the 
heads,  because  the  space  reserved  for  each  magnetic  flux  region  on  the  perimeter  is  larger 
than  that  available  near  the  center  of  the  disk.  In  spite  of  their  greater  storage  capacity, 
however,  CLV  disks  (such  as  CD  ROMs)  usually  have  slower  access  times  than  CAV  disks 
because  of  the  constant  need  to  fine-tune  the  motor  speed  as  the  head  moves  from  track  to 
track.  Thus,  CAV  disks  are  preferred  for  MS-DOS  systems. 
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Heads 

Simple  disk  systems  use  a  single  disk,  or  platter,  and  use  one  or  two  sides  of  the  platter; 
more  complex  systems,  such  as  fixed  disks,  use  multiple  platters.  Disk  systems  that  use 
both  sides  of  a  disk  have  one  read/write  head  per  side;  the  heads  are  positioned  over  the 
track  to  be  read  from  or  written  to  by  means  of  a  positioning  mechanism  such  as  a  solenoid 
or  servomotor.  The  heads  are  ordinarily  moved  in  unison,  using  a  single  head-movement 
mechanism;  thus,  heads  on  opposite  sides  of  a  platter  in  a  double-sided  disk  system 
typically  access  the  same  logical  track  on  their  associated  sides  of  the  platter.  (Performance 
can  be  increased  by  increasing  the  number  of  heads  to  as  many  as  one  head  per  track, 
eliminating  the  positioning  mechanism.  However,  because  they  are  quite  expensive,  such 
multiple-head  systems  are  generally  found  only  on  high-performance  minicomputers  and 
mainframes.) 

The  set  of  like-numbered  tracks  on  the  two  sides  of  a  platter  (or  on  all  sides  of  all  platters 
in  a  multiplatter  system)  is  called  a  cylinder.  Disks  are  usually  partitioned  along  cylinders. 
Tracks  and  cylinders  may  appear  to  have  the  same  meaning;  however,  the  term  track  is 
used  to  define  a  concentric  ring  containing  a  specific  number  of  sectors  on  a  single  side  of 
a  single  platter,  whereas  the  term  cylinder  refers  to  the  number  of  like-numbered  tracks  on 
a  device  (Figure  3-2). 


>  1 
cylinder 


Figure  3-2.  Tracks  and  cylinders  on  a  fixed-disk  system. 

Sectors 

Each  track  is  divided  into  equal-size  portions  called  sectors.  The  size  of  a  sector  is  a  power 
of  2  and  is  usually  greater  than  128  bytes — typically,  512  bytes. 

Floppy  disks  are  either  hard-sectored  or  soft-sectored,  depending  on  the  disk  drive  and 
the  medium.  Hard-sectored  disks  are  implemented  using  a  series  of  small  holes  near  the 


88  The  MS-DOS  Encyclopedia 


Article  3:  MS-DOS  Storage  Devices 


center  of  the  disk  that  indicate  the  beginning  of  each  sector;  these  holes  are  read  by  a 
photosensor/LED  pair  built  into  the  disk  drive.  Soft-sectored  disks  are  implemented  by 
magnetically  marking  the  beginning  of  each  sector  when  the  disk  is  formatted.  A  soft- 
sectored  disk  has  a  single  hole  near  the  center  of  the  disk  Csee  Figure  3-1)  that  marks  the 
location  of  sector  0  for  reference  when  the  disk  is  formatted  or  when  error  detection  is  per¬ 
formed;  this  hole  is  also  read  by  a  photosensor/LED  pair.  Fixed  disks  use  a  special  imple¬ 
mentation  of  soft  sectors  (see  below).  A  hard-sectored  floppy  disk  cannot  be  used  in  a 
disk  drive  built  for  use  with  soft-sectored  floppy  disks  (and  vice  versa). 

In  addition  to  a  fixed  number  of  data  bytes,  both  sector  types  include  a  certain  amount  of 
overhead  information,  such  as  error  correction  and  sector  identification,  in  each  sector. 

The  structure  of  each  sector  is  implemented  during  the  formatting  process. 

Standard  fixed  disks  and  5.25-inch  floppy  disks  generally  have  from  8  to  17  physical  sec¬ 
tors  per  track.  Sectors  are  numbered  beginning  at  1.  Each  sector  is  uniquely  identified  by  a 
complete  specification  of  the  read/write  head,  cylinder  number,  and  sector  number.  To 
access  a  particular  sector,  the  disk  drive  controller  hardware  moves  all  heads  to  the  speci¬ 
fied  cylinder  and  then  activates  the  appropriate  head  for  the  read  or  write  operation. 

The  read/write  heads  are  mechanically  positioned  using  one  of  two  hardware  implemen¬ 
tations.  The  first  method,  used  with  floppy  disks,  employs  an  “open-loop”  servomecha¬ 
nism  in  which  the  software  computes  where  the  heads  should  be  and  the  hardware  moves 
them  there.  (A  servomechanism  is  a  device  that  can  move  a  solenoid  or  hold  it  in  a  fixed 
position.)  An  open-loop  system  employs  no  feedback  mechanism  to  determine  whether 
the  heads  were  positioned  correctly — the  hardware  simply  moves  the  heads  to  the 
requested  position  and  returns  an  error  if  the  information  read  there  is  not  what  was 
expected.  The  positioning  mechanism  in  floppy-disk  drives  is  made  with  close  tolerances 
because  if  the  positioning  of  the  heads  on  two  drives  differs,  disks  written  on  one  might 
not  be  usable  on  the  other. 

Most  fixed  disk  systems  use  the  second  method — a  “closed-loop”  servomechanism  that 
reserves  one  side  of  one  platter  for  positioning  information.  This  information,  which  indi¬ 
cates  where  the  tracks  and  sectors  are  located,  is  written  on  the  disk  at  the  factory  when 
the  drive  is  assembled.  Positioning  the  read/write  heads  in  a  closed-loop  system  is  actually 
a  two-step  process:  First,  the  head  assembly  is  moved  to  the  approximate  location  of  the 
read  or  write  operation;  then  the  disk  controller  reads  the  closed-loop  servo  information, 
compares  it  to  the  desired  location,  and  fine-tunes  the  head  position  accordingly.  This 
fine-tuning  approach  yields  faster  access  times  and  also  allows  for  higher-capacity  disks 
because  the  positioning  can  be  more  accurate  and  the  distances  between  tracks  can 
therefore  be  smaller.  Because  the  “servo  platter”  usually  has  positioning  information  on 
one  side  and  data  on  the  other,  many  systems  have  an  odd  number  of  read/write  heads 
for  data. 

Interleaving 

CAV  MS-DOS  disks  are  described  in  terms  of  bytes  per  sector,  sectors  per  track,  number  of 
cylinders,  and  number  of  read/write  heads.  Overall  access  time  is  based  on  how  fast  the 
disk  rotates  (rotational  latency)  and  how  fast  the  heads  can  move  from  track  to  track 
(track-to-track  latency). 
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On  most  fixed  disks,  the  sectors  on  the  disk  are  logically  or  physically  numbered  so  that 
logically  sequential  sectors  are  not  physically  adjacent  (Figure  3-3).  The  underlying  princi¬ 
ple  is  that,  because  the  controller  cannot  finish  processing  one  sector  before  the  next 
sequential  sector  arrives  under  the  read/write  head,  the  logically  numbered  sectors  must 
be  staggered  around  the  track.  This  staggering  of  sectors  is  called  skewing  or,  more  com¬ 
monly,  interleaving.  A  2-to-l  (2:1)  interleave  places  sequentially  accessed  sectors  so  that 
there  is  one  additional  sector  between  them;  a  3:1  interleave  places  two  additional  sectors 
between  them.  A  slower  disk  controller  needs  a  larger  interleave  factor.  A  3:1  interleave 
means  that  three  revolutions  are  required  to  read  all  sectors  on  a  track  in  numeric  order. 

Rotation  direction 


One  approach  to  improving  fixed-disk  performance  is  to  decrease  the  interleave  ratio. 
This  generally  requires  a  specialized  utility  program  and  also  requires  that  the  disk  be 
reformatted  to  adjust  to  the  new  layout.  Obviously,  a  1:1  interleave  is  the  most  efficient, 
provided  the  disk  controller  can  process  at  that  speed.  The  normal  interleave  for  an  IBM 
PCAT  and  its  standard  fixed  disk  and  disk  controller  is  3:1,  but  disk  controllers  are  avail¬ 
able  for  the  PC/AT  that  are  capable  of  handling  a  1:1  interleave.  Floppy  disks  on  MS-DOS- 
based  computers  all  have  a  1:1  interleave  ratio. 

Layout  of  a  partition 

For  several  reasons,  large  physical  block  devices  such  as  fixed  disks  are  often  logically  par¬ 
titioned  into  smaller  logical  block  devices  (Figure  3-4).  For  instance,  such  partitions  allow 
a  device  to  be  shared  among  different  operating  systems.  Partitions  can  also  be  used  to 
keep  the  size  of  each  logical  device  within  the  PC-DOS  32  MB  restriction  (important  for 
large  fixed  disks).  MS-DOS  permits  a  maximum  of  four  partitions. 

A  partitioned  block  device  has  a  partition  table  located  in  one  sector  at  the  beginning  of 
the  disk.  This  table  indicates  where  the  logical  block  devices  are  physically  located.  (Even 
a  partitioned  device  with  only  one  partition  usually  has  such  a  table.) 
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Under  the  MS-DOS  partitioning  standard,  the  first  physical  sector  on  the  fixed  disk  con¬ 
tains  the  partition  table  and  a  bootstrap  program  capable  of  checking  the  partition  table 
for  a  bootable  partition,  loading  the  bootable  partition’s  boot  sector,  and  transferring  con¬ 
trol  to  it.  The  partition  table,  located  at  the  end  of  the  first  physical  sector  of  the  disk,  can 
contain  a  maximum  of  four  entries; 


Offeet  From 

Start  of  Sector 

Size  (bytes) 

Description 

OIBEH 

16 

Partition  #4 

OICEH 

16 

Partition  #3 

OIDEH 

16 

Partition  #2 

OlEEH 

16 

Partition  #1 

OlFEH 

2 

Signature:  AA55H 

The  partitions  are  allocated  in  reverse 
information: 

order.  Each  l6-byte  entry  contains  the  following 

OffeetFrom 

Start  of  Entry 

Size  (bytes) 

Description 

OOH 

1 

Boot  indicator 

OlH 

1 

Beginning  head 

(more) 
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Offset  From 


Start  of  Entry 

Size  (bytes) 

Description 

02H 

1 

Beginning  sector 

03H 

1 

Beginning  cylinder 

04H 

1 

System  indicator 

05H 

1 

Ending  head 

06H 

1 

Ending  sector 

07H 

1 

Ending  cylinder 

OSH 

4 

Starting  sector  (relative  to  beginning 
of  disk) 

OCH 

4 

Number  of  sectors  in  partition 

The  boot  indicator  is  zero  for  a  nonbootable  partition  and  80H  for  a  bootable  (active)  parti¬ 
tion.  A  fixed  disk  can  have  only  one  bootable  partition.  (When  setting  a  bootable  partition, 
partition  programs  such  as  FDISK  reset  the  boot  indicators  for  all  other  partitions  to  zero.) 
See  USER  COMMANDS:  fdisk. 

The  system  indicators  are 


Code  Meaning 

OOH  Unknown 

OlH  MS-DOS,  12-bit  FAT 

04H  MS-DOS,  16-bit  FAT 

Each  partition’s  boot  sector  is  located  at  the  start  of  the  partition,  which  is  specified  in 
terms  of  beginning  head,  beginning  sector,  and  beginning  cylinder  numbers.  This  infor¬ 
mation,  stored  in  the  partition  table  in  this  order,  is  loaded  into  the  DX  and  CX  registers  by 
the  PC  ROM  BIOS  loader  routine  when  the  machine  is  turned  on  or  restarted.  The  starting 
sector  of  the  partition  relative  to  the  beginning  of  the  disk  is  also  indicated.  The  ending 
head,  sector,  and  cylinder  numbers,  also  included  in  the  partition  table,  specify  the  last  ac¬ 
cessible  sector  for  the  partition.  The  total  number  of  sectors  in  a  partition  is  the  difference 
between  the  starting  and  ending  head  and  cylinder  numbers  times  the  number  of  sectors 
per  cylinder. 

MS-DOS  versions  2.0  through  3.2  allow  only  one  MS-DOS  partition  per  partitioned  device. 
Various  device  drivers  have  been  implemented  that  use  a  different  partition  table  that 
allows  more  than  one  MS-DOS  partition  to  be  installed,  but  the  secondary  MS-DOS  parti¬ 
tions  are  usually  accessible  only  by  means  of  an  installable  device  driver  that  knows  about 
this  change.  (Even  with  additional  MS-DOS  partitions,  a  fixed  disk  can  have  only  one  boot¬ 
able  partition.) 
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Layout  of  a  file  system 

Block  devices  are  accessed  on  a  sector  basis.  The  MS-DOS  kernel,  through  the  device 
driver,  sees  a  block  device  as  a  logical  fixed-size  array  of  sectors  and  assumes  that  the  array 
contains  a  valid  MS-DOS  file  system.  The  device  driver,  in  turn,  translates  the  logical  sector 
requests  from  MS-DOS  into  physical  locations  on  the  block  device. 

The  initial  MS-DOS  file  system  is  written  to  the  storage  medium  by  the  MS-DOS  FORMAT 
program.  See  USER  COMMANDS:  format.  The  general  layout  for  the  file  system  is  shown 
in  Figure  3-5. 


The  boot  sector  is  always  at  the  beginning  of  a  partition.  It  contains  the  OEM  identifica¬ 
tion,  a  loader  routine,  and  a  BIOS  parameter  block  (BPB)  with  information  about  the 
device,  and  it  is  followed  by  an  optional  area  of  reserved  sectors.  See  The  Boot  Sector 
below.  The  reserved  area  has  no  specific  use,  but  an  OEM  might  require  a  more  complex 
loader  routine  and  place  it  in  this  area.  The  file  allocation  tables  (FATs)  indicate  how  the 
file  data  area  is  allocated;  the  root  directory  contains  a  fixed  number  of  directory  entries; 
and  the  file  data  area  contains  data  files,  subdirectory  files,  and  free  data  sectors. 
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All  the  areas  just  described — the  boot  sector,  the  FAT,  the  root  directory,  and  the  file  data 
area — are  of  fixed  size;  that  is,  they  do  not  change  after  FORMAT  sets  up  the  medium. 

The  size  of  each  of  these  areas  depends  on  various  factors.  For  instance,  the  size  of  the  FAT 
is  proportional  to  the  file  data  area.  The  root  directory  size  ordinarily  depends  on  the  type 
of  device;  a  single-sided  floppy  disk  can  hold  64  entries,  a  double-sided  floppy  disk  can 
hold  112,  and  a  fixed  disk  can  hold  256.  (RAMdisk  drivers  such  as  RAMDRIVE.SYS  and 
some  implementations  of  FORMAT  allow  the  number  of  directory  entries  to  be  specified.) 

The  file  data  area  is  allocated  in  terms  of  clusters.  A  cluster  is  a  fixed  number  of  con¬ 
tiguous  sectors.  Sector  size  and  cluster  size  must  be  a  power  of  2.  The  sector  size  is  usually 
512  bytes  and  the  cluster  size  is  usually  1,  2,  or  4  KB,  but  larger  sector  and  cluster  sizes  are 
possible.  Commonly  used  MS-DOS  cluster  sizes  are 


Disk  Type 

Sectors/Cluster 

Bytes/Cluster  * 

Single-sided  floppy  disk 

1 

512 

Double-sided  floppy  disk 

2 

1024 

PCAT  fixed  disk 

4 

2048 

PC/XT  fixed  disk 

8 

4096 

Other  fixed  disks 

16 

8192 

Other  fixed  disks 

32 

16384 

*  Assumes  512  bytes  per  sector. 


In  general,  larger  cluster  sizes  are  used  to  support  larger  fixed  disks.  Although  smaller  clus¬ 
ter  sizes  make  allocation  more  space-efficient,  larger  clusters  are  usually  more  efficient  for 
random  and  sequential  access,  especially  if  the  clusters  for  a  single  file  are  not  sequentially 
allocated. 

The  file  allocation  table  contains  one  entry  per  cluster  in  the  file  data  area.  Doubling  the 
sectors  per  cluster  will  also  halve  the  number  of  FAT  entries  for  a  given  partition.  See  The 
File  Allocation  Table  below. 

The  boot  sector 

The  boot  sector  (Figure  3-6)  contains  a  BIOS  parameter  block,  a  loader  routine,  and  some 
other  fields  useful  to  device  drivers.  The  BPB  describes  a  number  of  physical  parameters 
of  the  device,  as  well  as  the  location  and  size  of  the  other  areas  on  the  device.  The  device 
driver  returns  the  BPB  information  to  MS-DOS  when  requested,  so  that  MS-DOS  can  deter¬ 
mine  how  the  disk  is  configured. 

Figure  3-7  is  a  hexadecimal  dump  of  an  actual  boot  sector.  The  first  3  bytes  of  the  boot  sec¬ 
tor  shown  in  Figure  3-7  would  be  E9H  2CH  OOH  if  a  long  jump  were  used  instead  of  a  short 
one  (as  in  early  versions  of  MS-DOS).  The  last  2  bytes  in  the  sector,  55H  and  AAH,  are  a 
fixed  signature  used  by  the  loader  routine  to  verify  that  the  sector  is  a  valid  boot  sector. 
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OOH 

03H 


OBH 

ODH 

OEH 

lOH 

IIH 

13H 

15H 

16H 

18H 

lAH 

ICH 

lEH 


E9XXXXorEBXX90 


OEM  name  and  version  (8  bytes) 

- < - 

Bytes  per  sector  (2  bytes) 

Sectors  per  allocation  unit  (1  byte) 

Reserved  sectors,  starting  at  0  (2  bytes) 

Number  of  FATs  (1  byte) 

-  BPB 

Number  of  root-directory  entries  (2  bytes) 

Total  sectors  in  logical  volume  (2  bytes) 

Media  descriptor  byte 

Number  of  sectors  per  FAT  (2  bytes)  ^ _ 

Sectors  per  track  (2  bytes) 

Number  of  heads  (2  bytes) 

Number  of  hidden  sectors  (2  bytes) 


Loader  routine 


Figure  3-6.  Map  of  the  boot  sector  of  an  MS-DOS  disk.  Bytes  OBH  through  1 7H  are  the  BIOS  parameter  block 
(BPB). 


The  BPB  information  contained  in  bytes  OBH  through  17H  indicates  that  there  are 

512  bytes  per  sector 
2  sectors  per  cluster 

1  reserved  sector  (for  the  boot  sector) 

2  FATs 

112  root  directory  entries 
1440  sectors  on  the  disk 
F9H  media  descriptor 

3  sectors  per  FAT 
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0 
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72 

65 

OD 
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OD 

OA 

4E 
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2D 

53 

79 

73 

74 

65 

6D 

re. . . .Non-System 

01A0 

20 

64 

69 

73 

6B 

20 

6F 

72-20 

64 

69 

73 

6B 

20 

65 

72 

disk  or  disk  er 

01B0 

72 

6F 

72 

OD 

OA 

52 

65 

70-6C 

61 

63 

65 

20 

61 

6E 

64 

ror.. Replace  and 

01C0 

20 

70 

72 

65 

73 

73 

20 

61-6E 

79 

20 

6B 

65 

79 

20 

77 

press  any  key  w 

01D0 

68 

65 

6E 

20 

72 

65 

61 

64-79 

OD 

OA 

00 

00 

00 

00 

00 

hen  ready . 

01E0 

00 

00 

00 

00 

00 

00 

00 

00-00 

00 

00 

00 

00 

00 

00 

00 

01F0 

00 

00 

00 

00 

00 

00 

00 

00-00 

00 

00 

00 

00 

00 

55 

AA 

. * 

Figure  3-  7.  Hexadecimal  dump  of  an  MS-DOS  boot  sector.  The  BPB  is  highlighted. 


Additional  information  immediately  after  the  BPB  indicates  that  there  are  9  sectors  per 
track,  2  read/write  heads,  and  0  hidden  sectors. 

The  media  descriptor,  which  appears  in  the  BPB  and  in  the  first  byte  of  each  FAT,  is  used  to 
indicate  the  type  of  medium  currently  in  a  drive.  IBM-compatible  media  have  the  follow¬ 
ing  descriptors: 


Descriptor  Media  Type  MS-DOS  Versions 


0F8H 

Fixed  disk 

2,3 

OFOH 

3.5-inch,  2-sided,  18  sector 

3.2 

0F9H 

3.5-inch,  2-sided,  9  sector 

3.2 

0F9H 

5.25-inch,  2-sided,  15  sector 

3.x 

OFCH 

5.25-inch,  1-sided,  9  sector 

2.x,  3.x 

OFDH 

5.25-inch,  2-sided,  9  sector 

2.x,  3.x 

OFEH 

5.25-inch,  1-sided,  8  sector 

1.x,  2.x,  3.x 

OFFH 

5.25-inch,  2-sided,  8  sector 

1.x  (except  1.0),  2,  3 

OFEH 

8-inch,  1-sided,  single-density 

OFDH 

8-inch,  2-sided,  single-density 

OFEH 

8-inch,  1-sided,  double-density 

OFDH 

8-inch,  2-sided,  double-density 
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The  file  allocation  table 

The  file  allocation  table  provides  a  map  to  the  storage  locations  of  files  on  a  disk  by  indi¬ 
cating  which  clusters  are  allocated  to  each  file  and  in  what  order.  To  enable  MS-DOS  to 
locate  a  file,  the  file’s  directory  entry  contains  its  beginning  FAT  entry  number.  This  FAT 
entry,  in  turn,  contains  the  entry  number  of  the  next  cluster  if  the  file  is  larger  than  one 
cluster  or  a  last-cluster  number  if  there  is  only  one  cluster  associated  with  the  file.  A  file 
whose  size  implies  that  it  occupies  10  clusters  will  have  10  FAT  entries  and  9  FAT  links. 
(The  set  of  links  for  a  particular  file  is  called  a  chain.) 

Additional  copies  of  the  FAT  are  used  to  provide  backup  in  case  of  damage  to  the  first, 
or  primary,  FAT;  the  typical  floppy  disk  or  fixed  disk  contains  two  FATs.  The  FATs  are 
arranged  sequentially  after  the  boot  sector,  with  some  possible  intervening  reserved  area. 
MS-DOS  ordinarily  uses  the  primary  FAT  but  updates  all  FATs  when  a  change  occurs. 

It  also  compares  all  FATs  when  a  disk  is  first  accessed,  to  make  sure  they  match. 

MS-DOS  supports  two  types  of  FAT:  One  uses  12-bit  links;  the  other,  introduced  with 
version  3.0  to  accommodate  large  fixed  disks  with  more  than  4087  clusters,  uses  l6-bit 
links. 

The  first  two  entries  of  a  FAT  are  always  reserved  and  are  filled  with  a  copy  of  the  media 
descriptor  byte  and  two  (for  a  12-bit  FAT)  or  three  (for  a  l6-bit  FAT)  OFFH  bytes,  as  shown 
in  the  following  dumps  of  the  first  16  bytes  of  the  FAT: 

12-bit  FAT: 

F9  FF  FF  03  40  00  FF  6F-00  07  FO  FF  00  00  00  00 

16-bit  FAT: 

F8  FF  FF  FF  03  00  04  00-FF  FF  06  00  07  00  FF  FF 

The  remaining  FAT  entries  have  a  one-to-one  relationship  with  the  clusters  in  the  file  data 
area.  Each  cluster’s  use  status  is  indicated  by  its  corresponding  FAT  value.  (FORMAT  in¬ 
itially  marks  the  FAT  entry  for  each  cluster  as  free.)  The  use  status  is  one  of  the  following: 


12-bit 


l6-bit 


Meaning 


OOOH 

OOIH 

FF0-FF6H 

FF7H 

FF8-FFFH 
All  other  values 


OOOOH 

OOOIH 

FFF0-FFF6H 

FFF7H 

FFF8-FFFFH 
All  other  values 


Free  cluster 
Unused  code 
Reserved 

Bad  cluster;  cannot  be  used 

Last  cluster  of  file 

Link  to  next  cluster  in  file 
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If  a  FAT  entry  is  nonzero,  the  corresponding  cluster  has  been  allocated.  A  free  cluster  is 
found  by  scanning  the  FAT  from  the  beginning  to  find  the  first  zero  value.  Bad  clusters  are 
ordinarily  identified  during  formatting.  Figure  3-8  shows  a  typical  FAT  chain. 


FATentry:  012345  6789 


FFDH 

FFFH 

003H 

005H 

FF7H 

006H 

FFFH 

OOOH 

OOOH 

OOOH 

continues.. 

(4093) 

(4095) 

(3) 

(5) 

(4087) 

(6) 

(4095) 

(0) 

(0) 

(0) 

' - Unused;  available  cluster 


' —  Unusable 


’ —  Unused;  not  available 
I —  Disk  is  double-sided,  double-density 

Figure  3-8.  Space  allocation  in  the  FAT  for  a  typical  MS-DOS  disk. 

Free  FAT  entries  contain  a  link  value  of  zero;  a  link  value  of  1  is  never  used.  Thus,  the  first 
allocatable  link  number,  associated  with  the  first  available  cluster  in  the  file  data  area,  is  2, 
which  is  the  number  assigned  to  the  first  physical  cluster  in  the  file  data  area.  Figure  3-9 
shows  the  relationship  of  files,  FAT  entries,  and  clusters  in  the  file  data  area. 

There  is  no  logical  difference  between  the  operation  of  the  12-bit  and  l6-bit  FAT  entries; 
the  difference  is  simply  in  the  storage  and  access  methods.  Because  the  8086  is  specifically 
designed  to  manipulate  8-  or  l6-bit  values  efficiently,  the  access  procedure  for  the  12-bit 
FAT  is  more  complex  than  that  for  the  l6-bit  FAT  {see  Figures  3-10  and  3-11). 

Special  considerations 

The  FAT  is  a  highly  efficient  bookkeeping  system,  but  various  tradeoffs  and  problems  can 
occur.  One  tradeoff  is  having  a  partially  filled  cluster  at  the  end  of  a  file.  This  situation 
leads  to  an  efficiency  problem  when  a  large  cluster  size  is  used,  because  an  entire  cluster  is 
allocated,  regardless  of  the  number  of  bytes  it  contains.  For  example,  ten  100-byte  files  on  a 
disk  with  16  KB  clusters  use  l60  KB  of  disk  space;  the  same  files  on  a  disk  with  1  KB  clus¬ 
ters  use  only  10  KB — a  difference  of  150  KB,  or  15  times  less  storage  used  by  the  smaller 
cluster  size.  On  the  other  hand,  the  12-bit  FAT  routine  in  Figure  3-10  shows  the  difficulty 
(and  therefore  slowness)  of  moving  through  a  large  file  that  has  a  long  linked  list  of  many 
small  clusters.  Therefore,  the  nature  of  the  data  must  be  considered:  Large  database  appli¬ 
cations  work  best  with  a  larger  cluster  size;  a  smaller  cluster  size  allows  many  small  text 
files  to  fit  on  a  disk.  (The  programmer  writing  the  device  driver  for  a  disk  device  ordinarily 
sets  the  cluster  size.) 
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12-bit  FAT: 


Reserved  003H  FFFH  007H  OOOH 


004H  006H  FFFH 


16  bit  FAT: 


Reserved 


F8  FF  FF  FF  03  00  04  00  FF  FF  06  00  07  00  FF  FF  00  00 


Corresponding  FAT  entry 
2 

3 

4 

5 

6 

7 

8 

Figure  3-9.  Correspondence  between  the  FAT  and  the file  data  area. 


File  data  area 
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-  Obtain  the  next  link  number  from  a  12-bit  FAT 


Parameters : 

ax  =  current  entry  number 

ds:bx  =  address  of  FAT  (must  be  contiguous) 


Returns : 

ax  =  next  link  number 


;  Uses: 

ax,  bx. 

cx 

next 1 2 

proc 

near 

add 

bx,  ax 

shr 

ax,  1 

pushf 

add 

bx,  ax 

mov 

ax, [bx] 

popf 

jc 

shift 

and 

ax,0fffh 

ret 

shift: 

mov 

cx,  4 

shr 

ax,  cl 

ret 

next 1 2 

endp 

;  ds:bx  =  partial  index 
;  ax  =  offset/2 
;  carry  =  no  shift  needed 
;  save  carry 

;  ds:bx  =  next  cluster  number  index 
;  ax  =  next  cluster  number 
;  carry  =  no  shift  needed 
;  skip  if  using  top  12  bits 
;  ax  =  lower  12  bits 

;  cx  =  shift  count 

;  ax  =  top  12  bits  in  lower  12  bits 


Figure  3-10.  Assembly-language  routine  to  access  a  12-bit  FAT. 


- Obtain  the  next  link  number  from  a  1 6-bit  FAT 

Parameters : 

ax  =  current  entry  number 

ds:bx  =  address  of  FAT  (must  be  contiguous) 


Returns : 

ax  =  next  link  number 


;  Uses: 

ax,  bx. 

cx 

next  1 6 

proc 

near 

add 

ax,  ax 

;  ax  =  word  offset 

add 

bx,  ax 

;  ds:bx  =  next  link  number  index 

nextl 6 

mov 

ret 

endp 

ax, [bx] 

;  ax  =  next  link  number 

Figure  3-11-  Assembly-language  routine  to  access  a  16-bit  FAT. 
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Problems  with  corrupted  directories  or  FATs,  induced  by  such  events  as  power  failures 
and  programs  running  wild,  can  lead  to  greater  problems  if  not  corrected.  The  MS-DOS 
CHKDSK  program  can  detect  and  fix  some  of  these  problems.  See  USER  COMMANDS: 
CHKDSK.  For  example,  one  common  problem  is  dangling  allocation  lists  caused  by  the 
absence  of  a  directory  entry  pointing  to  the  start  of  the  list.  This  situation  often  results 
when  the  directory  entry  was  not  updated  because  a  file  was  not  closed  before  the  com¬ 
puter  was  turned  off  or  restarted.  The  effect  is  relatively  benign:  The  data  is  inaccessible, 
but  this  limitation  does  not  affect  other  file  allocation  operations.  CHKDSK  can  fix  this 
problem  by  making  a  new  directory  entry  and  linking  it  to  the  list. 

Another  difficulty  occurs  when  the  file  size  in  a  directory  entry  does  not  match  the  file 
length  as  computed  by  traversing  the  linked  list  in  the  FAT.  This  problem  can  result  in 
improper  operation  of  a  program  and  in  error  responses  from  MS-DOS. 

A  more  complex  (and  rarer)  problem  occurs  when  the  directory  entry  is  properly  set  up 
but  all  or  some  portion  of  the  linked  list  is  also  referenced  by  another  directory  entry.  The 
problem  is  grave,  because  writing  or  appending  to  one  file  changes  the  contents  of  the 
other  file.  This  error  usually  causes  severe  data  and/or  directory  corruption  or  causes  the 
system  to  crash. 

A  similar  difficulty  occurs  when  a  linked  list  terminates  with  a  free  cluster  instead  of  a 
last-cluster  number.  If  the  free  cluster  is  allocated  before  the  error  is  corrected,  the 
problem  eventually  reverts  to  the  preceding  problem.  An  associated  difficulty  occurs  if  a 
link  value  of  1  or  a  link  value  that  exceeds  the  size  of  the  FAT  is  encountered. 

In  addition  to  CHKDSK,  a  number  of  commercially  available  utility  programs  can  be  used 
to  assist  in  FAT  maintenance.  For  instance,  disk  reorganizers  can  be  used  to  essentially 
rearrange  the  FAT  and  adjust  the  directory  so  that  all  files  on  a  disk  are  laid  out  sequentially 
in  the  file  data  area  and,  of  course,  in  the  FAT. 

The  root  directory 

Directory  entries,  which  are  32  bytes  long,  are  found  in  both  the  root  directory  and  the 
subdirectories.  Each  entry  includes  a  filename  and  extension,  the  file’s  size,  the  starting 
FAT  entry,  the  time  and  date  the  file  was  created  or  last  revised,  and  the  file’s  attributes. 
This  structure  resembles  the  format  of  the  CP/M-style  file  control  blocks  (FCBs)  used  by 
the  MS-DOS  version  1.x  file  functions.  See  PROGRAMMING  IN  THE  MS-DOS 
ENVIRONMENT:  Programming  for  ms-dos:  Disk  Directories  and  Volume  Labels. 

The  MS-DOS  file-naming  convention  is  also  derived  from  CP/M:  an  eight-character  file¬ 
name  followed  by  a  three-character  file  type,  each  left  aligned  and  padded  with  spaces  if 
necessary.  Within  the  limitations  of  the  character  set,  the  name  and  type  are  completely 
arbitrary.  The  time  and  date  stamps  are  in  the  same  format  used  by  other  MS-DOS  func¬ 
tions  and  reflect  the  time  the  file  was  last  written  to. 

Figure  3-12  shows  a  dump  of  a  512-byte  directory  sector  containing  l6  directory  entries. 
(Each  entry  occupies  two  lines  in  this  example.)  The  byte  at  offset  OABH,  containing  a 
lOH,  signifies  that  the  entry  starting  at  OAOH  is  for  a  subdirectory.  The  byte  at  offset  l60H, 
containing  0E5H,  means  that  the  file  has  been  deleted.  The  byte  at  offset  8BH,  containing 
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the  value  OSH,  indicates  that  the  directory  entry  beginning  at  offset  80H  is  a  volume  label. 
Finally  the  zero  byte  at  offset  IEOH  marks  the  end  of  the  directory,  indicating  that  the  sub¬ 
sequent  entries  in  the  directory  have  never  been  used  and  therefore  need  not  be  searched 
(versions  2.0  and  later). 
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Figure  3-^2.  Hexadecimal  dump  of  a  512-byte  directory  sector. 


The  sector  shown  in  Figure  3-12  is  actually  an  example  of  the  first  directory  sector  in  the 
root  directory  of  a  bootable  disk.  Notice  that  lO.SYS  and  MSDOS.SYS  are  the  first  two  files 
in  the  directory  and  that  the  file  attribute  byte  (offset  OBH  in  a  directory  entry)  has  a 
binary  value  of  00100111,  indicating  that  both  files  have  hidden  (bit  1  =  1),  system  (bit  0  =  1), 
and  read-only  (bit  2  =  1)  attributes.  The  archive  bit  (bit  5)  is  also  set,  marking  the  files  for 
possible  backup. 
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The  root  directory  can  optionally  have  a  special  type  of  entry  called  a  volume  label,  iden¬ 
tified  by  an  attribute  type  of  OSH,  that  is  used  to  identify  disks  by  name.  A  root  directory 
can  contain  only  one  volume  label.  The  root  directory  can  also  contain  entries  that  point  to 
subdirectories;  such  entries  are  identified  by  an  attribute  type  of  lOH  and  a  file  size  of  zero. 
Programs  that  manipulate  subdirectories  must  do  so  by  tracing  through  their  chains  of 
clusters  in  the  FAT. 

Two  other  special  types  of  directory  entries  are  found  only  within  subdirectories.  These 
entries  have  the  filenames .  and  .•  and  correspond  to  the  current  directory  and  the  parent 
directory  of  the  current  directory.  These  special  entries,  sometimes  called  directory 
aliases,  can  be  used  to  move  quickly  through  the  directory  structure. 

The  maximum  pathname  length  supported  by  MS-DOS,  excluding  a  drive  specifier  but 
including  any  filename  and  extension  and  subdirectory  name  separators,  is  64  characters. 
The  size  of  the  directory  structure  itself  is  limited  only  by  the  number  of  root  directory 
entries  and  the  available  disk  space. 

The  file  area 

The  file  area  contains  subdirectories,  file  data,  and  unallocated  clusters.  The  area  is 
divided  into  fixed-size  clusters  and  the  use  for  a  particular  cluster  is  specified  by  the  corre¬ 
sponding  FAT  entry. 


other  MS-DOS  Storage  Devices 

As  mentioned  earlier,  MS-DOS  supports  other  types  of  storage  devices,  such  as  magnetic- 
tape  drives  and  CD  ROM  drives.  Tape  drives  are  most  often  used  for  archiving  and  for 
sequential  transaction  processing  and  therefore  are  not  discussed  here. 

CD  ROMs  are  compact  laser  discs  that  hold  a  massive  amount  of  information — a  single 
side  of  a  Cp  ROM  can  hold  almost  500  MB  of  data.  However,  there  are  some  drawbacks  to 
current  CD  ROM  technology.  For  instance,  data  cannot  be  written  to  them — the  informa¬ 
tion  is  placed  on  the  compact  disk  at  the  factory  when  the  disk  is  made  and  is  available  on 
a  read-only  basis.  In  addition,  the  access  time  for  a  CD  ROM  is  much  slower  than  for  most 
magnetic-disk  systems.  Even  with  these  limitations,  however,  the  ability  to  hold  so  much 
information  makes  CD  ROM  a  good  method  for  storing  large  amounts  of  static  information. 
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Article  4 

Structure  of  an  Application  Program 


Planning  an  MS-DOS  application  program  requires  serious  analysis  of  the  program’s  size. 
This  analysis  can  help  the  programmer  determine  which  of  the  two  program  styles  sup¬ 
ported  by  MS-DOS  best  suits  the  application.  The  .EXE  program  structure  provides  a  large 
program  with  benefits  resulting  from  the  extra  512  bytes  (or  more)  of  header  that  preface 
all  .EXE  files.  On  the  other  hand,  at  the  cost  of  losing  the  extra  benefits,  the  .COM  program 
structure  does  not  burden  a  small  program  with  the  overhead  of  these  extra  header  bytes. 

Because  .COM  programs  start  their  lives  as  .EXE  programs  (before  being  converted  by 
EXE2BIN)  and  because  several  aspects  of  application  programming  under  MS-DOS 
remain  similar  regardless  of  the  program  structure  used,  a  solid  understanding  of  .EXE 
structures  is  beneficial  even  to  the  programmer  who  plans  on  writing  only  .COM  pro¬ 
grams.  Therefore,  we’ll  begin  our  discussion  with  the  structure  and  behavior  of  .EXE 
programs  and  then  look  at  differences  between  .COM  programs  and  .EXE  programs, 
including  restrictions  on  the  structure  and  content  of  .COM  programs. 


The  .EXE  Program 

The  .EXE  program  has  several  advantages  over  the  .COM  program  for  application  design. 
Considerations  that  could  lead  to  the  choice  of  the  .EXE  format  include 

•  Extremely  large  programs 

•  Multiple  segments 

•  Overlays 

•  Segment  and  far  address  constants 

•  Long  calls 

•  Possibility  of  upgrading  programs  to  MS  OS/2  protected  mode 

The  principal  advantages  of  the  .EXE  format  are  provided  by  the  file  header.  Most 
important,  the  header  contains  information  that  permits  a  program  to  make  direct  seg¬ 
ment  address  references — a  requirement  if  the  program  is  to  grow  beyond  64  KB. 

The  file  header  also  tells  MS-DOS  how  much  memory  the  program  requires.  This  informa¬ 
tion  keeps  memory  not  required  by  the  program  from  being  allocated  to  the  program — 
an  important  consideration  if  the  program  is  to  be  upgraded  in  the  future  to  run  efficiently 
under  MS  OS/2  protected  mode. 

Before  discussing  the  .EXE  program  structure  in  detail,  we’ll  look  at  how  .EXE  programs 
behave. 
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Giving  control  to  the  .EXE  program 

Figure  4-1  gives  an  example  of  how  a  .EXE  program  might  appear  in  memory  when 
MS-DOS  first  gives  the  program  control.  The  diagram  shows  Microsoft’s  preferred  pro¬ 
gram  segment  arrangement. 


Start  segment 
and  start  of 
program  image 
(load  module) 


Any  segments  with  class 
STACK 

All  segments 
declared  ) 

Any  segments  with  class 
BSS 

as  part  of  group 
DGROUP 

Any  DGROUP  segments 
not  shown  elsewhere 

L 

Any  segments  with  class 
BEGDATA 

Any  segments  with  class  names 
ending  with  CODE 

Program  segment  prefix  (PSP) 


◄  SP 

◄  SS 


◄  IP 

◄  CS 


'  ◄  DS,ES 


Figure  4-1.  The  .EXE  program:  memory  map  diagram  with  register  pointers. 


Before  transferring  control  to  the  .EXE  program,  MS-DOS  initializes  various  areas  of 
memory  and  several  of  the  microprocessor’s  registers.  The  following  discussion  explains 
what  to  expect  from  MS-DOS  before  it  gives  the  .EXE  program  control. 

The  program  segment  prefix 

The  program  segment  prefix  (PSP)  is  not  a  direct  result  of  any  program  code.  Rather,  this 
special  256-byte  (l6-paragraph)  page  of  memory  is  built  by  MS-DOS  in  front  of  all  .EXE 
and  .COM  programs  when  they  are  loaded  into  memory.  Although  the  PSP  does  contain 
several  fields  of  use  to  newer  programs,  it  exists  primarily  as  a  remnant  of  CP/M — 
Microsoft  adopted  the  PSP  for  ease  in  porting  the  vast  number  of  programs  available  under 
CP/M  to  the  MS-DOS  environment.  Figure  4-2  shows  the  fields  that  make  up  the  PSP. 

PSP.'OOOOH  (Terminate  [old  Warm  Boot]  Vector)  The  PSP  begins  with  an  8086-family 
INT  20H  instruction,  which  the  program  can  use  to  transfer  control  back  to  MS-DOS.  The 
PSP  includes  this  instruction  at  offset  OOH  because  this  address  was  the  WBOOT  (Warm 
Boot/Terminate)  vector  under  CP/M  and  CP/M  programs  usually  terminated  by  jumping 
to  this  vector.  This  method  of  termination  should  not  be  used  in  newer  programs.  See 
Terminating  the  .EXE  Program  below. 

PSP:0002H(Addressof  Last  Segment  Allocated  to  Program)  MS-DOS  introduced  the  word 
at  offset  02H  into  the  PSP.  It  contains  the  segment  address  of  the  paragraph  following  the 
block  of  memory  allocated  to  the  program.  This  address  should  be  used  only  to  determine 
the  size  or  the  end  of  the  memory  block  allocated  to  the  program;  it  must  not  be  con¬ 
sidered  a  pointer  to  free  memory  that  the  program  can  appropriate.  In  most  cases  this  ad¬ 
dress  will  not  point  to  free  memory,  because  any  free  memory  will  already  have  been 
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Figure  4-2.  The  program  segment  prefix  (PSP). 

allocated  to  the  program  unless  the  program  was  linked  using  the  /CPARMAXALLOC 
switch.  Even  when  /CPARMAXALLOC  is  used,  MS-DOS  may  fit  the  program  into  a  block 
of  memory  only  as  big  as  the  program  requires.  Well-behaved  programs  should  acquire 
additional  memory  only  through  the  MS-DOS  function  calls  provided  for  that  purpose. 

PSP:0005H  (MS-DOS  Function  Call  [old  BDOSJ  Vector)  Offset  05H  is  also  a  hand-me- 
down  from  CP/M.  This  location  contains  an  8086-family  far  (intersegment)  call  instruction 
to  MS-DOS’s  function  request  handler.  (Under  CP/M,  this  address  was  the  Basic  Disk  Oper¬ 
ating  System  [BDOS]  vector,  which  served  a  similar  purpose.)  This  vector  should  not  be 
used  to  call  MS-DOS  in  newer  programs.  The  System  Calls  section  of  this  book  explains 
the  newer,  approved  method  for  calling  MS-DOS.  MS-DOS  provides  this  vector  only  to  sup¬ 
port  CP/M-style  programs  and  therefore  honors  only  the  CP/M-style  functions  (00-24H) 
through  it. 

PSP:000AH-0015H  (Parent's  22H,  23H,  and  24H  Interrupt  Vector  Save)  MS-DOS  uses 
offsets  OAH  through  15H  to  save  the  contents  of  three  program-specific  interrupt  vectors. 
MS-DOS  must  save  these  vectors  because  it  permits  any  program  to  execute  another  pro¬ 
gram  (called  a  child  process)  through  an  MS-DOS  function  call  that  returns  control  to  the 
original  program  when  the  called  program  terminates.  Because  the  original  program 
resumes  executing  when  the  child  program  terminates,  MS-DOS  must  restore  these  three 
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interrupt  vectors  for  the  original  program  in  case  the  called  program  changed  them.  The 
three  vectors  involved  include  the  program  termination  handler  vector  (Interrupt  22H), 
the  Control-C/Control-Break  handler  vector  (Interrupt  23H),  and  the  critical  error  handler 
vector  (Interrupt  24H).  MS-DOS  saves  the  original  preexecution  contents  of  these  vectors 
in  the  child  program’s  PSP  as  doubleword  fields  beginning  at  offsets  OAH  for  the  program 
termination  handler  vector,  OEH  for  the  Control-C/Control-Break  handler  vector,  and  12H 
for  the  critical  error  handler  vector. 

PSP:002CH  (Segment  Address  of  Environment)  Under  MS-DOS  versions  2.0  and  later,  the 
word  at  offset  2CH  contains  one  of  the  most  useful  pieces  of  information  a  program  can 
find  in  the  PSP — the  segment  address  of  the  first  paragraph  of  the  MS-DOS  environment. 
This  pointer  enables  the  program  to  search  through  the  environment  for  any  configuration 
or  directory  search  path  strings  placed  there  by  users  with  the  SET  command. 

PSP:0050H  (New  MS-DOS  Call  Vector)  Many  programmers  disregard  the  contents  of  offset 
50H.  The  location  consists  simply  of  an  INT  21H  instruction  followed  by  a  RETF.  A  .EXE 
program  can  call  this  location  using  a  far  call  as  a  means  of  accessing  the  MS-DOS  function 
handler.  Of  course,  the  program  can  also  simply  do  an  INT  21H  directly,  which  is  smaller 
and  faster  than  calling  50H.  Unlike  calls  to  offset  05H,  calls  to  offset  50H  can  request  the 
full  range  of  MS-DOS  functions. 

PSP:005CH  (Default  File  Control  Block  1)  and  PSPOOGCH  (Default  File  Control  Block  2) 
MS-DOS  parses  the  first  two  parameters  the  user  enters  in  the  command  line  following  the 
program’s  name.  If  the  first  parameter  qualifies  as  a  valid  (limited)  MS-DOS  filename 
(the  name  can  be  preceded  by  a  drive  letter  but  not  a  directory  path),  MS-DOS  initializes 
offsets  5CH  through  6BH  with  the  first  l6  bytes  of  an  unopened  file  control  block  (FCB)  for 
the  specified  file.  If  the  second  parameter  also  qualifies  as  a  valid  MS-DOS  filename, 
MS-DOS  initializes  offsets  6CH  through  7BH  with  the  first  l6  bytes  of  an  unopened  FCB  for 
the  second  specified  file.  If  the  user  specifies  a  directory  path  as  part  of  either  filename, 
MS-DOS  initializes  only  the  drive  code  in  the  associated  FCB.  Many  programmers  no 
longer  use  this  feature,  because  file  access  using  FCBs  does  not  support  directory  paths 
and  other  newer  MS-DOS  features. 

Because  FCBs  expand  to  37  bytes  when  the  file  is  opened,  opening  the  first  FCB  at  offset 
5CH  causes  it  to  grow  from  l6  bytes  to  37  bytes  and  to  overwrite  the  second  FCB.  Similarly, 
opening  the  second  FCB  at  offset  6CH  causes  it  to  expand  and  to  overwrite  the  first  part  of 
the  command  tail  and  default  disk  transfer  area  (DTA).  (The  command  tail  and  default 
DTA  are  described  below.)  To  use  the  contents  of  both  default  FCBs,  the  program  should 
copy  the  FCBs  to  a  pair  of  37-byte  fields  located  in  the  program’s  data  area.  The  program 
can  use  the  first  FCB  without  moving  it  only  after  relocating  the  second  FCB  (if  necessary) 
and  only  by  performing  sequential  reads  or  writes  when  using  the  first  FCB.  To  perform 
random  reads  and  writes  using  the  first  FCB,  the  programmer  must  either  move  the  first 
FCB  or  change  the  default  DTA  address.  Otherwise,  the  first  FCB’s  random  record  field  will 
overlap  the  start  of  the  default  DTA.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRON¬ 
MENT:  Programming  for  ms-dos:  File  and  Record  Management. 
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PSP:0080H  (Command  Tail  and  Default  DTA)  The  default  DTA  resides  in  the  entire  sec¬ 
ond  half  (128  bytes)  of  the  PSP.  MS-DOS  uses  this  area  of  memory  as  the  default  record 
buffer  if  the  program  uses  the  FCB-style  file  access  functions.  Again,  MS-DOS  inherited 
this  location  from  CP/M.  (MS-DOS  provides  a  function  the  program  can  call  to  change  the 
address  MS-DOS  will  use  as  the  current  DTA.  See  SYSTEM  CALLS:  Interrupt  21h:  Func¬ 
tion  lAH.)  Because  the  default  DTA  serves  no  purpose  until  the  program  performs  some 
file  activity  that  requires  it,  MS-DOS  places  the  command  tail  in  this  area  for  the  program 
to  examine.  The  command  tail  consists  of  any  text  the  user  types  following  the  program 
name  when  executing  the  program.  Normally,  an  ASCII  space  (20H)  is  the  first  character 
in  the  command  tail,  but  any  character  MS-DOS  recognizes  as  a  separator  can  occupy  this 
position.  MS-DOS  stores  the  command-tail  text  starting  at  offset  81H  and  always  places  an 
ASCII  carriage  return  (ODH)  at  the  end  of  the  text.  As  an  additional  aid,  it  places  the  length 
of  the  command  tail  at  offset  80H.  This  length  includes  all  characters  except  the  final  ODH. 
For  example,  the  command  line 

OdOIT  with  class  <Enter> 

will  result  in  the  program  DOIT  being  executed  with  PSP:0080H  containing 

OB  20  57  49  54  48  20  43  4C  41  53  53  OD 
len  sp  W  I  T  H  sp  C  L  A  S  S  cr 

The  stack 

Because  .EXE-style  programs  did  not  exist  under  CP/M,  MS-DOS  expects  .EXE  programs 
to  operate  in  strictly  MS-DOS  fashion.  For  example,  MS-DOS  expects  the  .EXE  program  to 
supply  its  own  stack,  (Figure  4-1  shows  the  program’s  stack  as  the  top  box  in  the  diagram.) 

Microsoft’s  high-level-language  compilers  create  a  stack  themselves,  but  when  writing  in 
assembly  language  the  programmer  must  specifically  declare  one  or  more  segments  with 
the  STACK  combine  type.  If  the  programmer  declares  multiple  stack  segments,  possibly  in 
different  source  modules,  the  linker  combines  them  into  one  large  segment.  See  Control¬ 
ling  the  .EXE  Program’s  Structure  below. 

Many  programmers  declare  their  stack  segments  as  preinitialized  with  some  recognizable 
repeating  string  such  as  *STACK  This  makes  it  possible  to  examine  the  program’s  stack  in 
memory  (using  a  debugger  such  as  DEBUG)  to  determine  how  much  stack  space  the  pro¬ 
gram  actually  used.  On  the  other  hand,  if  the  stack  is  left  as  uninitialized  memory  and 
linked  at  the  end  of  the  .EXE  program,  it  will  not  require  space  within  the  .EXE  file.  (The 
reason  for  this  will  become  more  apparent  when  we  examine  the  structure  of  a  .EXE  file.) 

Note:  When  multiple  stack  segments  have  been  declared  in  different  .ASM  files,  the 
,  Microsoft  Object  Linker  (LINK)  correctly  allocates  the  total  amount  of  stack  space  speci¬ 
fied  in  all  the  source  modules,  but  the  initialization  data  from  all  modules  is  overlapped 
module  by  module  at  the  high  end  of  the  combined  segment. 

An  important  difference  between  .COM  and  .EXE  programs  is  that  MS-DOS  preinitializes 
a  .COM  program’s  stack  with  a  termination  address  before  transferring  control  to  the  pro¬ 
gram.  MS-DOS  does  not  do  this  for  .EXE  programs,  so  a  .EXE  program  cannot  simply 
execute  an  8086-family  RET  instruction  as  a  means  of  terminating. 


Section  II:  Programming  in  the  MS-DOS  Environment  111 


Part  B:  Programming  for  MS-DOS 


Note:  In  the  assembly-language  files  generated  for  a  Microsoft  C  program  or  for  programs 
in  most  other  high-level-languages,  the  compiler’s  placement  of  a  RET  instruction  at  the 
end  of  the  main  function/subroutine/procedure  might  seem  confusing.  After  all,  MS-DOS 
does  not  place  any  return  address  on  the  stack.  The  compiler  places  the  RET  at  the  end  of 
main  because  main  does  not  receive  control  directly  from  MS-DOS.  A  library  initializa¬ 
tion  routine  receives  control  from  MS-DOS;  this  routine  then  calls  main.  When  main  per¬ 
forms  the  RET,  it  returns  control  to  a  library  termination  routine,  which  then  terminates 
back  to  MS-DOS  in  an  approved  manner. 

Preallocated  memory 

While  loading  a  .EXE  program,  MS-DOS  performs  several  steps  to  determine  the  initial 
amount  of  memory  to  be  allocated  to  the  program.  First,  MS-DOS  reads  the  two  values  the 
linker  places  near  the  start  of  the  .EXE  header:  The  first  value,  MINALLOC,  indicates  the 
minimum  amount  of  extra  memory  the  program  requires  to  start  executing;  the  second 
value,  MAXALLOC,  indicates  the  maximum  amount  of  extra  memory  the  program  would 
like  allocated  before  it  starts  executing.  Next,  MS-DOS  locates  the  largest  free  block  of 
memory  available.  If  the  size  of  the  program’s  image  within  the  .EXE  file  combined  with 
the  value  specified  for  MINALLOC  exceeds  the  memory  block  it  found,  MS-DOS  returns 
an  error  to  the  process  trying  to  load  the  program.  If  that  process  is  COMMAND.COM, 
COMMAND.COM  then  displays  a  Program  too  big  to  fit  in  memory  error  message  and 
terminates  the  user’s  execution  request.  If  the  block  exceeds  the  program’s  MINALLOC 
requirement,  MS-DOS  then  compares  the  memory  block  against  the  program’s  image 
combined  with  the  MAXALLOC  request.  If  the  free  block  exceeds  the  maximum  memory 
requested  by  the  program,  MS-DOS  allocates  only  the  maximum  request;  otherwise,  it 
allocates  the  entire  block.  MS-DOS  then  builds  a  PSP  at  the  start  of  this  block  and  loads 
the  program’s  image  from  the  .EXE  file  into  memory  following  the  PSP. 

This  process  ensures  that  the  extra  memory  allocated  to  the  program  will  immediately 
follow  the  program’s  image.  The  same  will  not  necessarily  be  true  for  any  memory 
MS-DOS  allocates  to  the  program  as  a  result  of  MS-DOS  function  calls  the  program  per¬ 
forms  during  its  execution.  Only  function  calls  requesting  MS-DOS  to  increase  the  initial 
allocation  can  guarantee  additional  contiguous  memory.  (Of  course,  the  granting  of  such 
increase  requests  depends  on  the  availability  of  free  memory  following  the  initial 
allocation.) 

Programmers  writing  .EXE  programs  sometimes  find  the  lack  of  keywords  or  compiler/ 
assembler  switches  that  deal  with  MINALLOC  (and  possibly  MAXALLOC)  confusing.  The 
programmer  never  explicitly  specifies  a  MINALLOC  value  because  LINK  sets  MINALLOC 
to  the  total  size  of  all  uninitialized  data  and/or  stack  segments  linked  at  the  very  end  of  the 
program.  The  MINALLOC  field  allows  the  compiler  to  indicate  the  size  of  the  initialized 
data  fields  in  the  load  module  without  actually  including  the  fields  themselves,  resulting  in 
a  smaller  .EXE  program  file.  For  LINK  to  minimize  the  size  of  the  .EXE  file,  the  program 
must  be  coded  and  linked  in  such  a  way  as  to  place  all  uninitialized  data  fields  at  the  end 
of  the  program.  Microsoft  high-level-language  compilers  handle  this  automatically; 
assembly-language  programmers  must  give  LINK  a  little  help. 
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Note:  Beginning  and  even  advanced  assembly-language  programmers  can  easily  fall  into 
an  argument  with  the  assembler  over  field  addressing  when  attempting  to  place  data  fields 
after  the  code  in  the  source  file.  This  argument  can  be  avoided  if  programmers  use  the 
SEGMENT  and  GROUP  assembler  directives.  See  Controlling  the  .EXE  Program’s  Struc¬ 
ture  below. 

No  reliable  method  exists  for  the  linker  to  determine  the  correct  MAXALLOC  value 
required  by  the  .EXE  program.  Therefore,  LINK  uses  a  “safe”  value  of  FFFFH,  which 
causes  MS-DOS  to  allocate  all  of  the  largest  block  of  free  memory — which  is  usually  all 
free  memory — to  the  program.  Unless  a  program  specifically  releases  the  memory  for 
which  it  has  no  use,  it  denies  multitasking  supervisor  programs,  such  as  IBM’s  TopView, 
any  memory  in  which  to  execute  additional  programs — hence  the  rule  that  a  well- 
behaved  program  releases  unneeded  memory  during  its  initiali2ation.  Unfortunately,  this 
memory  conservation  approach  provides  no  help  if  a  multitasking  supervisor  supports  the 
ability  to  load  several  programs  into  memory  without  executing  them.  Therefore,  pro¬ 
grams  that  have  correctly  established  MAXALLOC  values  actually  are  well-behaved 
programs. 

To  this  end,  newer  versions  of  Microsoft  LINK  include  the  /CPARMAXALLOC  switch 
to  permit  specification  of  the  maximum  amount  of  memory  required  by  the  program.  The 
/CPARMAXALLOC  switch  can  also  be  used  to  set  MAXALLOC  to  a  value  that  is  known  to 
be  less  than  MINALLOC.  For  example,  specifying  a  MAXALLOC  value  of  1  (/CP:1)  forces 
MS-DOS  to  allocate  only  MINALLOC  extra  paragraphs  to  the  program.  In  addition, 
Microsoft  supplies  a  program  called  EXEMOD  with  most  of  its  languages.  This  program 
permits  modification  of  the  MAXALLOC  field  in  the  headers  of  existing  .EXE  programs. 
See  Modifying  the  .EXE  File  Header  below. 

The  registers 

Figure  4-1  gives  a  general  indication  of  how  MS-DOS  sets  the  8086-family  registers 
before  transferring  control  to  a  .EXE  program.  MS-DOS  determines  most  of  the  original 
register  values  from  information  the  linker  places  in  the  .EXE  file  header  at  the  start  of  the 
.EXE  file. 

MS-DOS  sets  the  SS  register  to  the  segment  (paragraph)  address  of  the  start  of  any  seg¬ 
ments  declared  with  the  STACK  combine  type  and  sets  the  SP  register  to  the  offset  from  SS 
of  the  byte  immediately  after  the  combined  stack  segments.  (If  no  stack  segment  is 
declared,  MS-DOS  sets  SS:SP  to  CS:0000.)  Because  in  the  8086-family  architecture  a  stack 
grows  from  high  to  low  memory  addresses,  this  effectively  sets  SS:SP  to  point  to  the  base  of 
the  stack.  Therefore,  if  the  programmer  declares  stack  segments  when  writing  an  assem¬ 
bly-language  program,  the  program  will  not  need  to  initialize  the  SS  and  SP  registers. 
Microsoft’s  high-level-language  compilers  handle  the  creation  of  stack  segments  automati¬ 
cally.  In  both  cases,  the  linker  determines  the  initial  SS  and  SP  values  and  places  them  in 
the  header  at  the  start  of  the  .EXE  program  file. 

Unlike  its  handling  of  the  SS  and  SP  registers,  MS-DOS  does  not  initialize  the  DS  and  ES 
registers  to  any  data  areas  of  the  .EXE  program.  Instead,  it  points  DS  and  ES  to  the  start  of 
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the  PSP.  It  does  this  for  two  primary  reasons:  First,  MS-DOS  uses  the  DS  and  ES  registers  to 
tell  the  program  the  address  of  the  PSP;  second,  most  programs  start  by  examining  the 
command  tail  within  the  PSP.  Because  the  program  starts  without  DS  pointing  to  the  data 
segments,  the  program  must  initialize  DS  and  (optionally)  ES  to  point  to  the  data  segments 
before  it  starts  trying  to  access  any  fields  in  those  segments.  Unlike  .COM  programs,  .EXE 
programs  can  do  this  easily  because  they  can  make  direct  references  to  segments,  as 
follows: 


MOV  AX,SEG  DATA_SEGMENT_OR_GROUP_NAME 

MOV  DS,AX 

MOV  ES,AX 

High-level-language  programs  need  not  initialize  and  maintain  DS  and  ES;  the  compiler 
and  library  support  routines  do  this. 

In  addition  to  pointing  DS  and  ES  to  the  PSP,  MS-DOS  also  sets  AH  and  AL  to  reflect  the 
validity  of  the  drive  identifiers  it  placed  in  the  two  FCBs  contained  in  the  PSP.  MS-DOS  sets 
AL  to  OFFH  if  the  first  FCB  at  PSP:005CH  was  initialized  with  a  nonexistent  drive  identifier; 
otherwise,  it  sets  AL  to  zero.  Similarly,  MS-DOS  sets  AH  to  reflect  the  drive  identifier 
placed  in  the  second  FCB  at  PSP:006CH. 

When  MS-DOS  analyzes  the  first  two  command-line  parameters  following  the  program 
name  in  order  to  build  the  first  and  second  FCBs,  it  treats  any  character  followed  by  a 
colon  as  a  drive  prefix.  If  the  drive  prefix  consists  of  a  lowercase  letter  (ASCII  a  through 
z),  MS-DOS  starts  by  converting  the  character  to  uppercase  (ASCII  A  through  Z).  Then  it 
subtracts  40H  from  the  character,  regardless  of  its  original  value.  This  converts  the  drive 
prefix  letters  A  through  Z  to  the  drive  codes  OlH  through  lAH,  as  required  by  the  two 
FCBs.  Finally,  MS-DOS  places  the  drive  code  in  the  appropriate  FCB. 

This  process  does  not  actually  preclude  invalid  drive  specifications  from  being  placed  in 
the  FCBs.  For  instance,  MS-DOS  will  accept  the  drive  prefix ! :  and  place  a  drive  code  of 
OEIH  in  the  FCB  (!  =  21H;  21H-40H  =  OEIH).  However,  MS-DOS  will  then  check  the  drive 
code  to  see  if  it  represents  an  existing  drive  attached  to  the  computer  and  will  pass  a  value 
of  OFFH  to  the  program  in  the  appropriate  register  (AL  or  AH)  if  it  does  not. 

As  a  side  effect  of  this  process,  MS-DOS  accepts  @:  as  a  valid  drive  prefix  because  the 
subtraction  of  40H  converts  the  @  character  (40H)  to  OOH.  MS-DOS  accepts  the  OOH  value 
as  valid  because  a  OOH  drive  code  represents  the  current  default  drive.  MS-DOS  will  leave 
the  FCB’s  drive  code  set  to  OOH  rather  than  translating  it  to  the  code  for  the  default  drive 
because  the  MS-DOS  function  calls  that  use  FCBs  accept  the  OOH  code. 

Finally,  MS-DOS  initializes  the  CS  and  IP  registers,  transferring  control  to  the  program’s 
entry  point.  Programs  developed  using  high-level-language  compilers  usually  receive  con¬ 
trol  at  a  library  initialization  routine.  A  programmer  writing  an  assembly-language  pro¬ 
gram  using  the  Microsoft  Macro  Assembler  (MASM)  can  declare  any  label  within  the 
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program  as  the  entry  point  by  placing  the  label  after  the  END  statement  as  the  last  line  of  the 
program: 

END  ENTRY_POINT_LABEL 

With  multiple  source  files,  only  one  of  the  files  should  have  a  label  following  the  END 
statement.  If  more  than  one  source  file  has  such  a  label,  LINK  uses  the  first  one  it  encoun¬ 
ters  as  the  entry  point. 

The  other  processor  registers  (BX,  CX,  DX,  BP,  SI,  and  DI)  contain  unknown  values  when 
the  program  receives  control  from  MS-DOS.  Once  again,  high-level-language  program¬ 
mers  can  ignore  this  fact — the  compiler  and  library  support  routines  deal  with  the  situa¬ 
tion.  However,  assembly-language  programmers  should  keep  this  fact  in  mind.  It  may  give 
needed  insight  sometime  in  the  future  when  a  program  functions  at  certain  times  and 
not  at  others. 

In  many  cases,  debuggers  such  as  DEBUG  and  SYMDEB  initialize  uninitialized  registers  to 
some  predictable  but  undocumented  state.  For  instance,  some  debuggers  may  predictably 
set  BP  to  zero  before  starting  program  execution.  However,  a  program  must  not  rely  on 
such  debugger  actions,  because  MS-DOS  makes  no  such  promises.  Situations  like  this 
could  account  for  a  program  that  fails  when  executed  directly  under  MS-DOS  but  works 
fine  when  executed  using  a  debugger. 

Terminating  the  .EXE  program 

After  MS-DOS  has  given  the  .EXE  program  control  and  it  has  completed  whatever  task 
it  set  out  to  perform,  the  program  needs  to  give  control  back  to  MS-DOS.  Because  of 
MS-DOS’s  evolution,  five  methods  of  program  termination  have  accumulated — not 
including  the  several  ways  MS-DOS  allows  programs  to  terminate  but  remain  resident 
in  memory. 

Before  using  any  of  the  termination  methods  supported  by  MS-DOS,  the  program  should 
always  close  any  files  it  had  open,  especially  those  to  which  data  has  been  written  or 
whose  lengths  were  changed.  Under  versions  2.0  and  later,  MS-DOS  closes  any  files 
opened  using  handles.  However,  good  programming  practice  dictates  that  the  program 
not  rely  on  the  operating  system  to  close  the  program’s  files.  In  addition,  programs  written 
to  use  shared  files  under  MS-DOS  versions  3.0  and  later  should  release  any  file  locks  before 
closing  the  files  and  terminating. 

The  Terminate  Process  with  Return  Code  function 

Of  the  five  ways  a  program  can  terminate,  only  the  Interrupt  21H  Terminate  Process  with 
Return  Code  function  (4CH)  is  recommended  for  programs  running  under  MS-DOS  ver¬ 
sion  2.0  or  later.  This  method  is  one  of  the  easiest  approaches  to  terminating  any  pro¬ 
gram,  regardless  of  its  structure  or  segment  register  settings.  The  Terminate  Process  with 
Return  Code  function  call  simply  consists  of  the  following: 

MOV  AH, 4CH  ; load  the  MS-DOS  function  code 

MOV  AL, RETURN-CODE  ;load  the  termination  code 

INT  21 H  /call  MS-DOS  to  terminate  program 
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The  example  loads  the  AH  register  with  the  Terminate  Process  with  Return  Code  function 
code.  Then  it  loads  the  AL  register  with  a  return  code.  Normally,  the  return  code  repre¬ 
sents  the  reason  the  program  terminated  or  the  result  of  any  operation  the  program 
performed. 

A  program  that  executes  another  program  as  a  child  process  can  recover  and  analyze  the 
child  program’s  return  code  if  the  child  process  used  this  termination  method.  Likewise, 
the  child  process  can  recover  the  RETlJRN_CODE  returned  by  any  program  it  executes  as 
a  child  process.  When  a  program  is  terminated  using  this  method  and  control  returns  to 
MS-DOS,  a  batch  (.BAT)  file  can  be  used  to  test  the  terminated  program’s  return  code 
using  the  IFERRORLEVEL  statement. 

Only  two  general  conventions  have  been  adopted  for  the  value  of  RETURN-CODE; 

First,  a  RETURN_CODE  value  of  OOH  indicates  a  normal  no-error  termination  of  the 
program;  second,  increasing  RETURN_CODE  values  indicate  increasing  severity  of  con¬ 
ditions  under  which  the  program  terminated.  For  instance,  a  compiler  could  use  the 
RETURN_CODE  OOH  if  it  found  no  errors  in  the  source  file,  OlH  if  it  found  only  warning 
errors,  or  02H  if  it  found  severe  errors. 

If  a  program  has  no  need  to  return  any  special  RETURN_CODE  values,  then  the  following 
instructions  will  suffice  to  terminate  the  program  with  a  RETURN-CODE  of  OOH: 

MOV  AX, 4C00H 

INT  21 H 

Apart  from  being  the  approved  termination  method.  Terminate  Process  with  Return  Code 
is  easier  to  use  with  .EXE  programs  than  any  other  termination  method  because  all  other 
methods  require  that  the  CS  register  point  to  the  start  of  the  PSP  when  the  program  termi¬ 
nates.  This  restriction  causes  problems  for  .EXE  programs  because  they  have  code  seg¬ 
ments  with  segment  addresses  different  from  that  of  the  PSP. 

The  only  problem  with  Terminate  Process  with  Return  Code  is  that  it  is  not  available  under 
MS-DOS  versions  earlier  than  2.0,  so  it  cannot  be  used  if  a  program  must  be  compatible 
with  early  MS-DOS  versions.  However,  Figure  4-3  shows  how  a  program  can  use  the 
approved  termination  method  when  available  but  still  remain  pre-2.0  compatible.  See  The 
Warm  Boot/Terminate  Vector  below. 

TEXT  SEGMENT  PARA  PUBLIC  'CODE' 

ASSUME  CS : TEXT, DS : NOTHING, ES :NOTHING, SS : NOTHING 

TERM_VECTOR  DD  ? 

ENTRY_PROC  PROC  FAR 

;save  pointer  to  termination  vector  in  PSP 

MOV  WORD  PTR  CS : TERM_VECTOR+0, OOOOh  ;save  offset  of  Warm  Boot  vector 

MOV  WORD  PTR  CS : TERM_VECTOR+2, DS  /save  segment  address  of  PSP 

Figure  4-3.  Terminating  properly  under  any  MS-DOS  version.  (more) 
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;*****  Place  main  task  here  ***** 

/determine  which  MS-DOS  version  is  active,  take  jump  if  2.0  or  later 


MOV 

AH,30h 

/load  Get  MS-DOS  Version  Number  function  code 

INT 

21h 

/call  MS-DOS  to 

get  version  number 

OR 

AL,AL 

/see  if  pre-2. 0 

MS-DOS 

JNZ 

TERM_0200 

/jump  if  2.0  or 

later 

/terminate  under  pre-2 . 0  MS-DOS 

JMP  CS : TERM_VECTOR  /jump  to  Warm  Boot  vector  in  PSP 

/terminate  under  MS-DOS  2.0  or  later 


TERML0200: 

MOV 

INT 

ENTRY_PROC 

TEXT  ENDS 

END 


AX,4C00h 

21h 

ENDP 

ENTRY_PROC 


Figure  4-3.  Continued. 


/load  MS-DOS  termination  function  code 

/and  return  code 

/call  MS-DOS  to  terminate 


/define  entry  point 


The  Terminate  Program  interrupt 

Before  MS-DOS  version  2.0,  terminating  with  an  approved  method  meant  executing 
an  INT  20H  instruction,  the  Terminate  Program  interrupt.  The  INT  20H  instruction  was 
replaced  as  the  approved  termination  method  for  two  primary  reasons:  First,  it  did  not 
provide  a  means  whereby  programs  could  return  a  termination  code;  second,  CS  had 
to  point  to  the  PSP  before  the  INT  20H  instruction  was  executed. 

The  restriction  placed  on  the  value  of  CS  at  termination  did  not  pose  a  problem  for  .COM 
programs  because  they  execute  with  CS  pointing  to  the  beginning  of  the  PSP.  A  .EXE  pro¬ 
gram,  on  the  other  hand,  executes  with  CS  pointing  to  various  code  segments  of  the  pro¬ 
gram,  and  the  value  of  CS  cannot  be  changed  arbitrarily  when  the  program  is  ready  to 
terminate.  Because  of  this,  few  .EXE  programs  attempt  simply  to  execute  a  Terminate  Pro¬ 
gram  interrupt  from  directly  within  their  own  code  segments.  Instead,  they  usually  use 
the  termination  method  discussed  next. 

The  Warm  Boot/Terminate  vector 

The  earlier  discussion  of  the  structure  of  the  PSP  briefly  covered  one  older  method  a  .EXE 
program  can  use  to  terminate:  Offset  OOH  within  the  PSP  contains  an  INT  20H  instruction 
to  which  the  program  can  jump  in  order  to  terminate.  MS-DOS  adopted  this  technique  to 
support  the  many  CP/M  programs  ported  to  MS-DOS.  Under  CP/M,  this  PSP  location  was 
referred  to  as  the  Warm  Boot  vector  because  the  CP/M  operating  system  was  always 
reloaded  from  disk  (rebooted)  whenever  a  program  terminated. 
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Because  offset  OOH  in  the  PSP  contains  an  INT  20H  instruction,  jumping  to  that  location 
terminates  a  program  in  the  same  manner  as  an  INT  20H  included  directly  within  the  pro¬ 
gram,  but  with  one  important  difference:  By  jumping  to  PSPiOOOOH,  the  program  sets  the 
CS  register  to  point  to  the  beginning  of  the  PSP,  thereby  satisfying  the  only  restriction 
imposed  on  executing  the  Terminate  Program  interrupt.  The  discussion  of  MS-DOS  Func¬ 
tion  4CH  gave  an  example  of  how  a  .EXE  program  can  terminate  via  PSPiOOOOH.  The  ex¬ 
ample  first  asks  MS-DOS  for  its  version  number  and  then  terminates  via  PSPiOOOOH  only 
under  versions  of  MS-DOS  earlier  than  2.0.  Programs  can  also  use  PSPiOOOOH  under 
MS-DOS  versions  2.0  and  later;  the  example  uses  Function  4CH  simply  because  it  is 
preferred  under  the  later  MS-DOS  versions. 

The  RET  instruction 

The  other  popular  method  used  by  CP/M  programs  to  terminate  involved  simply  execut¬ 
ing  a  RET  instruction.  This  worked  because  CP/M  pushed  the  address  of  the  Warm  Boot 
vector  onto  the  stack  before  giving  the  program  control.  MS-DOS  provides  this  support 
only  for  .COM-style  programs;  it  does  not  push  a  termination  address  onto  the  stack 
before  giving  .EXE  programs  control. 

The  programmer  who  wants  to  use  the  RET  instruction  to  return  to  MS-DOS  can  use  the 
variation  of  the  Figure  4-3  listing  shown  in  Figure  4-4. 

TEXT  SEGMENT  PARA  PUBLIC  ’CODE’ 

ASSUME  CS : TEXT, DS : NOTHING, ES : NOTHING, SS : NOTHING 
ENTRY_PROC  PROC  FAR  ;make  proc  FAR  so  RET  will  be  FAR 


Push  pointer 

to  termination 

vector  in  PSP 

PUSH 

DS 

/push  PSP's  segment  address 

XOR 

AX,  AX 

/ax  =  0  =  offset  of  Warm  Boot  vector  in  PSP 

PUSH 

AX 

/push  Warm  Boot  vector  offset 

*****  Place 

main  task  here 

♦  *  *  *  ♦ 

Determine  which  MS-DOS  version  is  active,  take  jump  if  2.0  or  later 

MOV 

AH,30h 

/load  Get  MS-DOS  Version  Number  function  code 

INT 

21h 

/call  MS-DOS  to  get  version  number 

OR 

AL,AL 

/see  if  pre-2. 0  MS-DOS 

JNZ 

TERM_0200 

/jump  if  2.0  or  later 

/Terminate  under  pre-2 . 0  MS-DOS  (this  is  a  FAR  proc,  so  RET  will  be  FAR) 

RET  ;pop  PSP: OOH  into  CS : IP  to  terminate 

Figure  4-4.  Using  RET  to  return  control  to  MS-DOS.  (more) 
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/Terminate  under  MS-DOS  2.0  or  later 
TERM_0200: 

MOV 


INT 

ENTRY_PROC 

TEXT  ENDS 

END 


AX, 4C00h 
21h 

ENDP 

ENTRY_PROC 


;AH  =  MS-DOS  Terminate  Process  with  Return  Code 
/function  code,  AL  =  return  code  of  OOH 
/call  MS-DOS  to  terminate 


/declare  the  program's  entry  point 


Figure  4-4.  Continued. 


The  Terminate  Process  function 

The  final  method  for  terminating  a  .EXE  program  is  Interrupt  21H  Function  OOH  (Termi¬ 
nate  Process).  This  method  maintains  the  same  restriction  as  all  other  older  termination 
methods:  CS  must  point  to  the  PSP.  Because  of  this  restriction,  .EXE  programs  typically 
avoid  this  method  in  favor  of  terminating  via  PSPrOOOOH,  as  discussed  above  for  programs 
executing  under  versions  of  MS-DOS  earlier  than  2.0. 

Terminating  and  staying  resident 

A  .EXE  program  can  use  any  of  several  additional  termination  methods  to  return  con¬ 
trol  to  MS-DOS  but  still  remain  resident  within  memory  to  service  a  special  event.  See 
PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Terminate-and- 
Stay-Resident  Utilities. 

Structure  of  the  .EXE  files 

So  far  we’ve  examined  how  the  .EXE  program  looks  in  memory,  how  MS-DOS  gives  the 
program  control  of  the  computer,  and  how  the  program  should  return  control  to  MS-DOS. 
Next  we’ll  investigate  what  the  program  looks  like  as  a  disk  file,  before  MS-DOS  loads  it 
into  memory.  Figure  4-5  shows  the  general  structure  of  a  .EXE  file. 

The  file  header 

Unlike  .COM  program  files,  .EXE  program  files  contain  information  that  permits  the 
.EXE  program  and  MS-DOS  to  use  the  full  capabilities  of  the  8086  family  of  microproces¬ 
sors.  The  linker  places  all  this  extra  information  in  a  header  at  the  start  of  the  .EXE  file. 
Although  the  .EXE  file  structure  could  easily  accommodate  a  header  as  small  as  32  bytes, 
the  linker  never  creates  a  header  smaller  than  512  bytes.  (This  minimum  header  size  corre¬ 
sponds  to  the  standard  record  size  preferred  by  MS-DOS.)  The  .EXE  file  header  contains 
the  following  information,  which  MS-DOS  reads  into  a  temporary  work  area  in  memory 
for  use  while  loading  the  .EXE  program: 

OO—OIH  (.EXE  Signature)  MS-DOS  does  not  rely  on  the  extension  (.EXE  or  .COM)  to 
determine  whether  a  file  contains  a  .COM  or  a  .EXE  program.  Instead,  MS-DOS  recognizes 
the  file  as  a  .EXE  program  if  the  first  2  bytes  in  the  header  contain  the  signature  4DH  5AH 
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OxH  ^ 
IxH  ^ 


Use  Reloc 
Tbl  Ofsatl8H 
(offset  is  from 
start  of  file) 


Use  Header 
Paras  at  OSH 
(load  module  ^ 
always  starts  on 
paragraph  boundary) 


End  of  file  ^ 


xOH  xlH 

x2H  x3H 

x4H  x5H 

x6H  x7H 

x8H  x9H 

xAH  xBH 

xCH  xDH 

xEH  xFH 

Signature 
4DH  |5AH 

Last  Page  Size 
lo  byt|hi  byt 

File  Pages 
lo  bytjhi  byt 

Reloc  Items 
lo  bytjhi  byt 

Header  Paras 
lo  bytjhi  byt 

MINALLOC 
lo  bytjhi  byt 

MAXALLOC 
lo  bytjhi  byt 

PreReloc  SS 
lo  byt  jhi  byt 

Initial  SP 
ofs  lojofs  hi 

Neg  Chksum 
lo  byt|hi  byt 

Initial  IP 
ofs  lojofs  hi 

Prc  Reloc  CS 
seg  lojseg  hi 

Reloc  Tbl  Ofs 
lo  bytjhi  byt 

Overlay  Num 
lo  byt^i  byt 

Reserved 

Seg  Relocation  Ptr  #1 
ofs  lo|ofs  hijseg  lo|seg  hi 

Seg  Relocation  Ptr  #2 
ofs  lo|ofs  hi|seg  lojseg  hi 

Seg  Relocation  Ptr  #3 
ofs  lojofs  hi  1  seg  lojseg  hi 

Seg  Relocation  Ptr  #4 
ofs  lojofs  hijseg  lojseg  hi 

Seg  Relocation  Ptr  #n-3 


Seg  Relocation  Ptr  #n-2 


ofs  lo{ofs  hi|seg  lo|seg  hi|ofs  lo|ofs  hi|seg  lo|seg  hi| 


Seg  Relocation  Ptr  #n-l 
|ofs  lojofs  hi|seg  lo|seg  hi| 


Seg  Relocation  Ptr  #n 
|ofs  lo|ofs  hi  I  seg  lo|seg  hi| 


Program  image 
(load  module) 


Use  Last  Page  Size  at  02H 


Final  512-byte  page  as 


Use  Reloc 

Items 

at06H 


indicated  by  Pages  at  04H 


Figure  4-5.  Structure  of  a  .EXE file. 

(ASCII  characters  M  and  Z).  If  either  or  both  of  the  signature  bytes  contain  other  values, 
MS-DOS  assumes  the  file  contains  a  .COM  program,  regardless  of  the  extension.  The 
reverse  is  not  necessarily  true — that  is,  MS-DOS  does  not  accept  the  file  as  a  .EXE  pro¬ 
gram  simply  because  the  file  begins  with  a  .EXE  signature.  The  file  must  also  pass  several 
other  tests. 

02—03H  (Last  Page  Size)  The  word  at  this  location  indicates  the  actual  number  of  bytes 
in  the  final  512-byte  page  of  the  file.  This  word  combines  with  the  following  word  to  deter¬ 
mine  the  actual  size  of  the  file.  1 

04—05H  (File  Pages)  This  word  contains  a  count  of  the  total  number  of  512-byte  pages 
required  to  hold  the  file.  If  the  file  contains  1024  bytes,  this  word  contains  the  value  0002H; 
if  the  file  contains  1025  bytes,  this  word  contains  the  value  0003H.  The  previous  word  (Last 
Page  Size,  02-03H)  is  used  to  determine  the  number  of  valid  bytes  in  the  final  512-byte 
page.  Thus,  if  the  file  contains  1024  bytes,  the  Last  Page  Size  word  contains  OOOOH  because 
no  bytes  overflow  into  a  final  partly  used  page;  if  the  file  contains  1025  bytes,  the  Last  Page 
Size  word  contains  OOOIH  because  the  final  page  contains  only  a  single  valid  byte  (the 
1025th  byte). 

06—07H  (Relocation  Items)  This  word  gives  the  number  of  entries  that  exist  in  the  reloca¬ 
tion  pointer  table.  See  Relocation  Pointer  Table  below. 
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08— 09H  (Header  Paragraphs)  This  word  gives  the  size  of  the  .EXE  file  header  in  l6-byte 
paragraphs.  It  indicates  the  offset  of  the  program’s  compiled/assembled  and  linked  image 
(the  load  module)  within  the  .EXE  file.  Subtracting  this  word  from  the  two  file-size  words 
starting  at  02H  and  04H  reveals  the  size  of  the  program’s  image.  The  header  always  spans 
an  even  multiple  of  l6-byte  paragraphs.  For  example,  if  the  file  consists  of  a  512-byte 
header  and  a  513-byte  program  image,  then  the  file’s  total  size  is  1025  bytes.  As  discussed 
before,  the  Last  Page  Size  word  (02-03H)  will  contain  OOOIH  and  the  File  Pages  word 
(04-05H)  will  contain  0003H.  Because  the  header  is  512  bytes,  the  Header  Paragraphs 
word  (08-09H)  will  contain  32  (0020H).  (That  is,  32  paragraphs  times  l6  bytes  per  para¬ 
graph  totals  512  bytes.)  By  subtracting  the  512  bytes  of  the  header  from  the  1025-byte  total 
file  size,  the  size  of  the  program’s  image  can  be  determined — in  this  case,  513  bytes. 

OA—OBH (MIN ALLOC)  This  word  indicates  the  minimum  number  of  l6-byte  paragraphs 
the  program  requires  to  begin  execution  in  addition  to  the  memory  required  to  hold 
the  program’s  image.  MINALLOC  normally  represents  the  total  size  of  any  uninitialized 
data  and/or  stack  segments  linked  at  the  end  of  the  program.  LINK  excludes  the 
space  reserved  by  these  fields  from  the  end  of  the  .EXE  file  to  avoid  wasting  disk  space. 

If  not  enough  memory  remains  to  satisfy  MINALLOC  when  loading  the  program,  MS- 
DOS  returns  an  error  to  the  process  trying  to  load  the  program.  If  the  process  is 
COMMAND.COM,  COMMAND.COM  then  displays  a  Program  too  big  to  fit  in  memory 
error  message.  The  EXEMOD  utility  can  alter  this  field  if  desired.  See  Modifying  the  .EXE 
File  Header  below. 

OC-ODH  (MAX ALLOC)  This  word  indicates  the  maximum  number  of  l6-byte  paragraphs 
the  program  would  like  allocated  to  it  before  it  begins  execution.  MAXALLOC  indicates 
additional  memory  desired  beyond  that  required  to  hold  the  program’s  image.  MS-DOS 
uses  this  value  to  allocate  MAXALLOC  extra  paragraphs,  if  available.  If  MAXALLOC  para¬ 
graphs  are  not  available,  the  program  receives  the  largest  memory  block  available — at 
least  MINALLOC  additional  paragraphs.  The  programmer  could  use  the  MAXALLOC  field 
to  request  that  MS-DOS  allocate  space  for  use  as  a  print  buffer  or  as  a  program-maintained 
heap,  for  example. 

Unless  otherwise  specified  with  the  /CPARMAXALLOC  switch  at  link  time,  the  linker  sets 
MAXALLOC  to  FFFFH.  This  causes  MS-DOS  to  allocate  all  of  the  largest  block  of  memory 
it  has  available  to  the  program.  To  make  the  program  compatible  with  multitasking  super¬ 
visor  programs,  the  programmer  should  use  /CPARMAXALLOC  to  set  the  true  maximum 
number  of  extra  paragraphs  the  program  desires.  The  EXEMOD  utility  can  also  be  used 
to  alter  this  field. 

Note:  If  both  MINALLOC  and  MAXALLOC  have  been  set  to  OOOOH,  MS-DOS  loads  the 
program  as  high  in  memory  as  possible.  LINK  sets  these  fields  to  OOOOH  if  the  /HIGH 
switch  was  used;  the  EXEMOD  utility  can  also  be  used  to  modify  these  fields. 

OE—OFH  (Initial  SS  Value)  This  word  contains  the  paragraph  address  of  the  stack  segment 
relative  to  the  start  of  the  load  module.  At  load  time,  MS-DOS  relocates  this  value  by  adding 
the  program’s  start  segment  address  to  it,  and  the  resulting  value  is  placed  in  the  SS  regis¬ 
ter  before  giving  the  program  control.  (The  start  segment  corresponds  to  the  first  segment 
boundary  in  memory  following  the  PSP.) 
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10—llH  (Initial  SP  Value)  This  word  contains  the  absolute  value  that  MS-DOS  loads 
into  the  SP  register  before  giving  the  program  control.  Because  MS-DOS  always  loads  pro¬ 
grams  starting  on  a  segment  address  boundary,  and  because  the  linker  knows  the  size  of 
the  stack  segment,  the  linker  is  able  to  determine  the  correct  SP  offset  at  link  time;  there¬ 
fore,  MS-DOS  does  not  need  to  adjust  this  value  at  load  time.  The  EXEMOD  utility  can  be 
used  to  alter  this  field. 

12— 13H  (Complemented  Checksum)  This  word  contains  the  one’s  complement  of  the 
summation  of  all  words  in  the  .EXE  file.  Current  versions  of  MS-DOS  basically  ignore  this 
word  when  they  load  a  .EXE  program;  however,  future  versions  might  not.  When  LINK 
generates  a  .EXE  file,  it  adds  together  all  the  contents  of  the  .EXE  file  (including  the  .EXE 
header)  by  treating  the  entire  file  as  a  long  sequence  of  l6-bit  words.  During  this  addition, 
LINK  gives  the  Complemented  Checksum  word  (12-13H)  a  temporary  value  of  OOOOH.  If 
the  file  consists  of  an  odd  number  of  bytes,  then  the  final  byte  is  treated  as  a  word  with  a 
high  byte  of  OOH.  Once  LINK  has  totaled  all  words  in  the  .EXE  file,  it  performs  a  one’s 
complement  operation  on  the  total  and  records  the  answer  in  the  .EXE  file  header  at 
offsets  12-13H.  The  validity  of  a  .EXE  file  can  then  be  checked  by  performing  the  same 
word-totaling  process  as  LINK  performed.  The  total  should  be  FFFFH,  because  the  total 
will  include  LINK’S  calculated  complemented  checksum,  which  is  designed  to  give  the  file 
the  FFFFH  total. 

An  example  7-byte  .EXE  file  illustrates  how  .EXE  file  checksums  are  calculated.  (This 
is  a  totally  fictitious  file,  because  .EXE  headers  are  never  smaller  than  512  bytes.)  If  this  fic¬ 
titious  file  contained  the  bytes  8CH  C8H  8EH  D8H  BAH  lOH  B4H,  then  the  file’s  total 
would  be  calculated  using  C88CH+D88EH+10BAH+00B4H=1B288H.  (Overflow  past  l6 
bits  is  ignored,  so  the  value  is  interpreted  as  B288H.)  If  this  were  a  valid  .EXE  file,  then 
the  B288H  total  would  have  been  FFFFH  instead. 

14— 15H  (Initial  IP  Value)  This  word  contains  the  absolute  value  that  MS-DOS  loads  into 
the  IP  register  in  order  to  transfer  control  to  the  program.  Because  MS-DOS  always  loads 
programs  starting  on  a  segment  address  boundary,  the  linker  can  calculate  the  correct  IP 
offset  from  the  initial  CS  register  value  at  link  time;  therefore,  MS-DOS  does  not  need 
to  adjust  this  value  at  load  time. 

16—17H  (Pre-Relocated  Initial  CS  Value)  This  word  contains  the  initial  value,  relative  to 
the  start  of  the  load  module,  that  MS-DOS  places  in  the  CS  register  to  give  the  .EXE  pro¬ 
gram  control.  MS-DOS  adjusts  this  value  in  the  same  manner  as  the  initial  SS  value  before 
loading  it  into  the  CS  register. 

18— 19H  (Relocation  Table  Offset)  This  word  gives  the  offset  from  the  start  of  the  file  to 
the  relocation  pointer  table.  This  word  must  be  used  to  locate  the  relocation  pointer  table, 
because  variable-length  information  pertaining  to  program  overlays  can  occur  before  the 
table,  thus  causing  the  position  of  the  table  to  vary. 

lA—lBH (Overlay  Number)  This  word  is  normally  set  to  OOOOH,  indicating  that  the  .EXE 
file  consists  of  the  resident,  or  primary,  part  of  the  program.  This  number  changes  only  in 
files  containing  programs  that  use  overlays,  which  are  sections  of  a  program  that  remain 
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on  disk  until  the  program  actually  requires  them.  These  program  sections  are  loaded  into 
memory  by  special  overlay  managing  routines  included  in  the  run-time  libraries  supplied 
with  some  Microsoft  high-level-language  compilers. 

The  preceding  section  of  the  header  (00-lBH)  is  known  as  the  formatted  area.  Optional 
information  used  by  high-level-language  overlay  managers  can  follow  this  formatted  area. 
Unless  the  program  in  the  .EXE  file  incorporates  such  information,  the  relocation  pointer 
table  immediately  follows  the  formatted  header  area. 

Relocation  Pointer  Table  The  relocation  pointer  table  consists  of  a  list  of  pointers  to  words 
within  the  .EXE  program  image  that  MS-DOS  must  adjust  before  giving  the  program  con¬ 
trol.  These  words  consist  of  references  made  by  the  program  to  the  segments  that  make  up 
the  program.  MS-DOS  must  adjust  these  segment  address  references  when  it  loads  the  pro¬ 
gram,  because  it  can  load  the  program  into  memory  starting  at  any  segment  address 
boundary. 

Each  pointer  in  the  table  consists  of  a  doubleword.  The  first  word  contains  an  offset  from 
the  segment  address  given  in  the  second  word,  which  in  turn  indicates  a  segment  address 
relative  to  the  start  of  the  load  module.  Together,  these  two  words  point  to  a  third  word 
within  the  load  module  that  must  have  the  start  segment  address  added  to  it.  (The  start  seg¬ 
ment  corresponds  to  the  segment  address  at  which  MS-DOS  started  loading  the  program’s 
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image,  immediately  following  the  PSP.)  Figure  4-6  shows  the  entire  procedure  MS-DOS 
performs  for  each  relocation  table  entry. 

The  load  module 

The  load  module  starts  where  the  .EXE  header  ends  and  consists  of  the  fully  linked  image 
of  the  program.  The  load  module  appears  within  the  .EXE  file  exactly  as  it  would  appear  in 
memory  if  MS-DOS  were  to  load  it  at  segment  address  OOOOH.  The  only  changes  MS-DOS 
makes  to  the  load  module  involve  relocating  any  direct  segment  references. 

Although  the  .EXE  file  contains  distinct  segment  images  within  the  load  module,  it  pro¬ 
vides  no  information  for  separating  those  individual  segments  from  one  another.  Existing 
versions  of  MS-DOS  ignore  how  the  program  is  segmented;  they  simply  copy  the  load 
module  into  memory,  relocate  any  direct  segment  references,  and  give  the  program 
control. 

Loading  the  .EXE  program 

So  far  we’ve  covered  all  the  characteristics  of  the  .EXE  program  as  it  resides  in  memory 
and  on  disk.  We’ve  also  touched  on  all  the  steps  MS-DOS  performs  while  loading  the  .EXE 
program  from  disk  and  executing  it.  The  following  list  recaps  the  .EXE  program  loading 
process  in  the  order  in  which  MS-DOS  performs  it: 

1.  MS-DOS  reads  the  formatted  area  of  the  header  (the  first  IBH  bytes)  from  the  .EXE 
file  into  a  work  area. 

2.  MS-DOS  determines  the  size  of  the  largest  available  block  of  memory. 

3.  MS-DOS  determines  the  size  of  the  load  module  using  the  Last  Page  Size  (offset 
02H),  File  Pages  (offset  04H),  and  Header  Paragraphs  (offset  OSH)  fields  from  the 
header.  An  example  of  this  process  is  in  the  discussion  of  the  Header  Paragraphs 
field. 

4.  MS-DOS  adds  the  MINALLOC  field  (offset  OAH)  in  the  header  to  the  calculated  load- 
module  size  and  the  size  of  the  PSP  (lOOH  bytes).  If  this  total  exceeds  the  size  of  the 
largest  available  block,  MS-DOS  terminates  the  load  process  and  returns  an  error  to 
the  calling  process.  If  the  calling  process  was  COMMAND.COM,  COMMAND.COM 
then  displays  a  Program  too  big  to  fit  in  memory  error  message. 

5.  MS-DOS  adds  the  MAXALLOC  field  (offset  OCH)  in  the  header  to  the  calculated 
load-module  size  and  the  size  of  the  PSP.  If  the  memory  block  found  earlier  exceeds 
this  calculated  total,  MS-DOS  allocates  the  calculated  memory  size  to  the  program 
from  the  memory  block;  if  the  calculated  total  exceeds  the  block’s  size,  MS-DOS 
allocates  the  entire  block. 

6.  If  the  MINALLOC  and  MAXALLOC  fields  both  contain  OOOOH,  MS-DOS  uses  the 
calculated  load-module  size  to  determine  a  start  segment.  MS-DOS  calculates  the 
start  segment  so  that  the  load  module  will  load  into  the  high  end  of  the  allocated 
block.  If  either  MINALLOC  or  MAXALLOC  contains  nonzero  values  (the  normal 
case),  MS-DOS  establishes  the  start  segment  as  the  segment  following  the  PSP. 

7.  MS-DOS  loads  the  load  module  into  memory  starting  at  the  start  segment. 
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8.  MS-DOS  reads  the  relocation  pointers  into  a  work  area  and  relocates  the  load  mod¬ 
ule’s  direct  segment  references,  as  shown  in  Figure  4-6. 

9.  MS-DOS  builds  a  PSP  in  the  first  lOOH  bytes  of  the  allocated  memory  block.  While 
building  the  two  FCBs  within  the  PSP,  MS-DOS  determines  the  initial  values  for  the 
AL  and  AH  registers. 

10.  MS-DOS  sets  the  SS  and  SP  registers  to  the  values  in  the  header  after  the  start  seg¬ 
ment  is  added  to  the  SS  value. 

1 1 .  MS-DOS  sets  the  DS  and  ES  registers  to  point  to  the  beginning  of  the  PSP. 

12.  MS-DOS  transfers  control  to  the  .EXE  program  by  setting  CS  and  IP  to  the  values  in 
the  header  after  adding  the  start  segment  to  the  CS  value. 

Controlling  the  .EXE  program's  structure 

We’ve  now  covered  almost  every  aspect  of  a  completed  .EXE  program.  Next,  we’ll  discuss 
how  to  control  the  structure  of  the  final  .EXE  program  from  the  source  level.  We’ll  start  by 
covering  the  statements  provided  by  MASM  that  permit  the  programmer  to  define  the 
structure  of  the  program  when  programming  in  assembly  language.  Then  we’ll  cover  the 
five  standard  memory  models  provided  by  Microsoft’s  C  and  FORTRAN  compilers  (both 
version  4.0),  which  provide  predefined  structuring  over  which  the  programmer  has 
limited  control. 

The  MASM  SEGMENT  directive 

MASM’s  SEGMENT  directive  and  its  associated  ENDS  directive  mark  the  beginning  and 
end  of  a  program  segment.  Program  segments  contain  collections  of  code  or  data  that  have 
offset  addresses  relative  to  the  same  common  segment  address. 

In  addition  to  the  required  segment  name,  the  SEGMENT  directive  has  three  optional 
parameters: 

segname  SEGMENT  [align]  [combine]  ['class^] 

With  MASM,  the  contents  of  a  segment  can  be  defined  at  one  point  in  the  source  file  and 
the  definition  can  be  resumed  as  many  times  as  necessary  throughout  the  remainder  of 
the  file.  When  MASM  encounters  a  SEGMENT  directive  with  a  segname  it  has  previously 
encountered,  it  simply  resumes  the  segment  definition  where  it  left  off.  This  occurs  regard¬ 
less  of  the  combine  type  specified  in  the  SEGMENT  directive — the  combine  type  influ¬ 
ences  only  the  actions  of  the  linker.  See  The  combine  Type  Parameter  below. 

The  align  type  parameter 

The  optional  align  parameter  lets  the  programmer  send  the  linker  an  instruction  on  how 
to  align  a  segment  within  memory.  In  reality,  the  linker  can  align  the  segment  only  in  rela¬ 
tion  to  the  start  of  the  program’s  load  module,  but  the  result  remains  the  same  because 
MS-DOS  always  loads  the  module  aligned  on  a  paragraph  (l6-byte)  boundary.  (The  PAGE 
align  type  creates  a  special  exception,  as  discussed  below.) 

The  following  alignment  types  are  permitted: 

BYTE  This  align  type  instructs  the  linker  to  start  the  segment  on  the  byte  immediately 
following  the  previous  segment.  BYTE  alignment  prevents  any  wasted  memory  between 
the  previous  segment  and  the  BYTE-aligned  segment. 
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A  minor  disadvantage  to  BYTE  alignment  is  that  the  8086-family  segment  registers  might 
not  be  able  to  directly  address  the  start  of  the  segment  in  all  cases.  Because  they  can 
address  only  on  paragraph  boundaries,  the  segment  registers  may  have  to  point  as  many 
as  15  bytes  behind  the  start  of  the  segment.  This  means  that  the  segment  size  should  not 
be  more  than  15  bytes  short  of  64  KB.  The  linker  adjusts  offset  and  segment  address  refer¬ 
ences  to  compensate  for  differences  between  the  physical  segment  start  and  the  paragraph 
addressing  boundary. 

Another  possible  concern  is  execution  speed  on  true  l6-bit  8086-family  microprocessors. 
When  using  non-8088  microprocessors,  a  program  can  actually  run  faster  if  the  instruc¬ 
tions  and  word  data  fields  within  segments  are  aligned  on  word  boundaries.  This  permits 
the  l6-bit  processors  to  fetch  full  words  in  a  single  memory  read,  rather  than  having  to  per¬ 
form  two  single-byte  reads.  The  EVEN  directive  tells  MASM  to  align  instructions  and  data 
fields  on  word  boundaries;  however,  MASM  can  establish  this  alignment  only  in  relation  to 
the  start  of  the  segment,  so  the  entire  segment  must  start  aligned  on  a  word  or  larger 
boundary  to  guarantee  alignment  of  the  items  within  the  segment. 

WORD  This  align  type  instructs  the  linker  to  start  the  segment  on  the  next  word  bound¬ 
ary.  Word  boundaries  occur  every  2  bytes  and  consist  of  all  even  addresses  (addresses  in 
which  the  least  significant  bit  contains  a  zero).  WORD  alignment  permits  alignment  of  data 
fields  and  instructions  within  the  segment  on  word  boundaries,  as  discussed  for  the  BYTE 
alignment  type.  However,  the  linker  may  have  to  waste  1  byte  of  memory  between  the  pre¬ 
vious  segment  and  the  word-aligned  segment  in  order  to  position  the  new  segment  on  a 
word  boundary. 

Another  minor  disadvantage  to  WORD  alignment  is  that  the  8086-family  segment  registers 
might  not  be  able  to  directly  address  the  start  of  the  segment  in  all  cases.  Because  they  can 
address  only  on  paragraph  boundaries,  the  segment  registers  may  have  to  point  as  many  as 
14  bytes  behind  the  start  of  the  segment.  This  means  that  the  segment  size  should  not  be 
more  than  14  bytes  short  of  64  KB.  The  linker  adjusts  offset  and  segment  address  refer¬ 
ences  to  compensate  for  differences  between  the  physical  segment  start  and  the  paragraph 
addressing  boundary. 

PARA  This  align  type  instructs  the  linker  to  start  the  segment  on  the  next  paragraph 
boundary.  The  segments  default  to  PARA  if  no  alignment  type  is  specified.  Paragraph 
boundaries  occur  every  l6  bytes  and  consist  of  all  addresses  with  hexadecimal  values  end¬ 
ing  in  zero  (OOOOH,  OOlOH,  0020H,  and  so  forth).  Paragraph  alignment  ensures  that  the 
segment  begins  on  a  segment  register  addressing  boundary,  thus  making  it  possible  to  ad¬ 
dress  a  full  64  KB  segment.  Also,  because  paragraph  addresses  are  even  addresses,  PARA 
alignment  has  the  same  advantages  as  WORD  alignment.  The  only  real  disadvantage  to 
PARA  alignment  is  that  the  linker  may  have  to  waste  as  many  as  15  bytes  of  memory 
between  the  previous  segment  and  the  paragraph-aligned  segment. 

PAGE  This  align  type  instructs  the  linker  to  start  the  segment  on  the  next  page  boundary. 
Page  boundaries  occur  every  256  bytes  and  consist  of  all  addresses  in  which  the  low 
address  byte  equals  zero  (OOOOH,  OlOOH,  0200H,  and  so  forth).  PAGE  alignment  ensures 
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only  that  the  linker  positions  the  segment  on  a  page  boundary  relative  to  the  start  of  the 
load  module.  Unfortunately,  this  does  not  also  ensure  alignment  of  the  segment  on  an 
absolute  page  within  memory,  because  MS-DOS  only  guarantees  alignment  of  the  entire 
load  module  on  a  paragraph  boundary. 

When  a  programmer  declares  pieces  of  a  segment  with  the  same  name  in  different  source 
modules,  the  align  type  specified  for  each  segment  piece  influences  the  alignment  of  that 
specific  piece  of  the  segment.  For  example,  assume  the  following  two  segment  declara¬ 
tions  appear  in  different  source  modules: 

_DATA  SEGMENT  PARA  PUBLIC  'DATA' 

DB  '123' 

-DATA  ENDS 

-DATA  SEGMENT  PARA  PUBLIC  'DATA' 

DB  '456' 

-DATA  ENDS 

The  linker  starts  by  aligning  the  first  segment  piece  located  in  the  first  object  module  on  a 
paragraph  boundary,  as  requested.  When  the  linker  encounters  the  second  segment  piece 
in  the  second  object  module,  it  aligns  that  piece  on  the  first  paragraph  boundary  following 
the  first  segment  piece.  This  results  in  a  13-byte  gap  between  the  first  segment  piece  and 
the  second.  The  segment  pieces  must  exist  in  separate  source  modules  for  this  to  occur.  If 
the  segment  pieces  exist  in  the  same  source  module,  MASM  assumes  that  the  second  seg¬ 
ment  declaration  is  simply  a  resumption  of  the  first  and  creates  an  object  module  with 
segment  declarations  equivalent  to  the  following: 

-DATA  SEGMENT  PARA  PUBLIC  'DATA' 

DB  '123' 

DB  '456' 

-DATA  ENDS 

The  combine  type  parameter 

The  optional  combine  parameter  allows  the  programmer  to  send  directions  to  the  linker 
on  how  to  combine  segments  with  the  same  segname  occurring  in  different  object  mod¬ 
ules.  If  no  combine  type  is  specified,  the  linker  treats  such  segments  as  if  each  had  a  dif¬ 
ferent  segname.  The  combine  type  has  no  effect  on  the  relationship  of  segments  with 
different  segnames.  MASM  and  LINK  both  support  the  following  combine  types: 

PUBLIC  This  combine  type  instructs  the  linker  to  concatenate  multiple  segments  having 
the  same  segname  into  a  single  contiguous  segment.  The  linker  adjusts  any  address  refer¬ 
ences  to  labels  within  the  concatenated  segments  to  reflect  the  new  position  of  those 
labels  relative  to  the  start  of  the  combined  segment.  This  combine  type  is  useful  for  ac¬ 
cessing  code  or  data  in  different  source  modules  using  a  common  segment  register  value. 

STACK  This  combine  type  operates  similarly  to  the  PUBLIC  combine  type,  except  for 
two  additional  effects:  The  STACK  type  tells  the  linker  that  this  segment  comprises  part  of 
the  program’s  stack  and  initialization  data  contained  within  STACK  segments  is  handled 
differently  than  in  PUBLIC  segments.  Declaring  segments  with  the  STACK  combine  type 
permits  the  linker  to  determine  the  initial  SS  and  SP  register  values  it  places  in  the  .EXE 
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file  header.  Normally,  a  programmer  would  declare  only  one  STACK  segment  in  one  of  the 
source  modules.  If  pieces  of  the  stack  are  declared  in  different  source  modules,  the  linker 
will  concatenate  them  in  the  same  fashion  as  PUBLIC  segments.  However,  initialization 
data  declared  within  any  STACK  segment  is  placed  at  the  high  end  of  the  combined  STACK 
segments  on  a  module-by-module  basis.  Thus,  each  successive  module’s  initialization  data 
overlays  the  previous  module’s  data.  At  least  one  segment  must  be  declared  with  the 
STACK  combine  type;  otherwise,  the  linker  will  issue  a  warning  message  because  it  can¬ 
not  determine  the  program’s  initial  SS  and  SP  values.  (The  warning  can  be  ignored  if  the 
program  itself  initializes  SS  and  SP.) 

COMMON  This  combine  type  instructs  the  linker  to  overlap  multiple  segments  having 
the  same  segname.  The  length  of  the  resulting  segment  reflects  the  length  of  the  longest 
segment  declared.  If  any  code  or  data  is  declared  in  the  overlapping  segments,  the  data 
contained  in  the  final  segments  linked  replaces  any  data  in  previously  loaded  segments. 
This  combine  type  is  useful  when  a  data  area  is  to  be  shared  by  code  in  different  source 
modules. 

MEMORY  Microsoft’s  LINK  treats  this  combine  type  the  same  as  it  treats  the  PUBLIC 
type.  MASM,  however,  supports  the  MEMORY  type  for  compatibility  with  other  linkers 
that  use  Intel’s  definition  of  a  MEMORY  combine  type. 

AT  address  This  combine  type  instructs  LINK  to  pretend  that  the  segment  will  reside  at 
the  absolute  segment  address.  LINK  then  adjusts  all  address  references  to  the  segment  in 
accordance  with  the  masquerade.  LINK  will  not  create  an  image  of  the  segment  in  the 
load  module,  and  it  will  ignore  any  data  defined  within  the  segment.  This  behavior  is  con¬ 
sistent  with  the  fact  that  MS-DOS  does  not  support  the  loading  of  program  segments  into 
absolute  memory  segments.  All  programs  must  be  able  to  execute  from  any  segment  ad¬ 
dress  at  which  MS-DOS  can  find  available  memory.  The  SEGMENT  AT  address  combine 
type  is  useful  for  creating  templates  of  various  areas  in  memory  outside  the  program.  For 
instance,  SEGMENT  AT  OOOOH  could  be  used  to  create  a  template  of  the  8086-family  inter¬ 
rupt  vectors.  Because  data  contained  within  SEGMENT  AT  address  segments  is  suppressed 
by  LINK  and  not  by  MASM  (which  places  the  data  in  the  object  module),  it  is  possible  to 
use  .OBJ  files  generated  by  MASM  with  another  linker  that  supports  ROM  or  other  absolute 
code  generation  should  the  programmer  require  this  specialized  capability. 

ThecHnss  type  parameter 

The  class  parameter  provides  the  means  to  organize  different  segments  into  classifications. 
For  instance,  here  are  three  source  modules,  each  with  its  own  separate  code  and  data 
segments: 

/Module  "A" 

A_DATA  SEGMENT  PARA  PUBLIC  'DATA' 

/Module  "A"  data  fields 
A_DATA  ENDS 

A_CODE  SEGMENT  PARA  PUBLIC  'CODE' 

/Module  "A"  code 
A_CODE  ENDS 
END 


(more) 
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; Module  ”B” 

B_DATA  SEGMENT  PARA  PUBLIC  'DATA* 

/Module  "B"  data  fields 
B_DATA  ENDS 

B_CODE  SEGMENT  PARA  PUBLIC  'CODE* 

/Module  "B"  code 
B_CODE  ENDS 
END 

/Module  "C" 

C_DATA  SEGMENT  PARA  PUBLIC  'DATA* 

/Module  "C"  data  fields 
C_DATA  ENDS 

C_CODE  SEGMENT  PARA  PUBLIC  'CODE* 

/Module  "C"  code 
C_CODE  ENDS 
END 

If  the  'CODE'  and  'DATA'  class  types  are  removed  from  the  SEGMENT  directives  shown 
above,  the  linker  organizes  the  segments  as  it  encounters  them.  If  the  programmer  speci¬ 
fies  the  modules  to  the  linker  in  alphabetic  order,  the  linker  produces  the  following 
segment  ordering: 

A-DATA 

A_CODE 

B_DATA 

B_CODE 

C_DATA 

C_CODE 

However,  if  the  programmer  specifies  the  class  types  shown  in  the  sample  source  mod¬ 
ules,  the  linker  organizes  the  segments  by  classification  as  follows: 

'DATA*  class;  A_DATA 

B_DATA 
C_DATA 

'CODE*  class;  A_CODE 

B_CODE 
C_CODE 

Notice  that  the  linker  still  organizes  the  classifications  in  the  order  in  which  it  encounters 
the  segments  belonging  to  the  various  classifications.  To  completely  control  the  order  in 
which  the  linker  organizes  the  segments,  the  programmer  must  use  one  of  three  basic 
approaches.  The  preferred  method  involves  using  the  /DOSSEG  switch  with  the  linker. 
This  produces  the  segment  ordering  shown  in  Figure  4-1.  The  second  method  involves 
creating  a  special  source  module  tf^t  contains  empty  SEGMENT-ENDS  blocks  for  all  the 
segments  declared  in  the  various  other  source  modules.  The  programmer  creates  the  list 
in  the  order  the  segments  are  to  be  arranged  in  memory  and  then  specifies  the  .OBJ  file  for 
this  module  as  the  first  file  for  the  linker  to  process.  This  procedure  establishes  the  order 
of  all  the  segments  before  LINK  begins  processing  the  other  program  modules,  so  the 
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programmer  can  declare  segments  in  these  other  modules  in  any  convenient  order.  For 
instance,  the  following  source  module  rearranges  the  result  of  the  previous  example  so 
that  the  linker  places  the  'CODE'  class  before  the  'DATA'  class: 

A_CODE  SEGMENT  PARA  PUBLIC  'CODE* 

A_CODE  ENDS 

B_CODE  SEGMENT  PARA  PUBLIC  'CODE* 

B_CODE  ENDS 

C_CODE  SEGMENT  PARA  PUBLIC  'CODE* 

C_CODE  ENDS 

A_DATA  SEGMENT  PARA  PUBLIC  'DATA* 

A_DATA  ENDS 

B_DATA  SEGMENT  PARA  PUBLIC  'DATA* 

B_DATA  ENDS 

C_DATA  SEGMENT  PARA  PUBLIC  'DATA' 

C_OATA  ENDS 

END 

Rather  than  creating  a  new  module,  the  third  method  places  the  same  segment  ordering 
list  shown  above  at  the  start  of  the  first  module  containing  actual  code  or  data  that  the 
programmer  will  be  specifying  for  the  linker.  This  duplicates  the  approach  used  by 
Microsoft’s  newer  compilers,  such  as  C  version  4.0. 

The  ordering  of  segments  within  the  load  module  has  no  direct  effect  on  the  linker’s 
adjustment  of  address  references  to  locations  within  the  various  segments.  Only  the 
GROUP  directive  and  the  SEGMENT  directive’s  combine  parameter  affect  address 
adjustments  performed  by  the  linker.  See  The  MASM  GROUP  Directive  below. 

Note:  Certain  older  versions  of  the  IBM  Macro  Assembler  wrote  segments  to  the  object 
file  in  alphabetic  order  regardless  of  their  order  in  the  source  file.  These  older  versions  can 
limit  efforts  to  control  segment  ordering.  Upgrading  to  a  new  version  of  the  assembler  is 
the  best  solution  to  this  problem. 

Ordering  segments  to  shrink  the  .EXE  file 

Correct  segment  ordering  can  significantly  decrease  the  size  of  a  .EXE  program  as  it 
resides  on  disk.  This  size-reduction  ordering  is  achieved  by  placing  all  uninitialized  data 
fields  in  their  own  segments  and  then  controlling  the  linker’s  ordering  of  the  program’s 
segments  so  that  the  uninitialized  data  field  segments  all  reside  at  the  end  of  the  program. 
When  the  program  modules  are  assembled,  MASM  places  information  in  the  object  mod¬ 
ules  to  tell  the  linker  about  initialized  and  uninitialized  areas  of  all  segments.  The  linker 
then  uses  this  information  to  prevent  the  writing  of  uninitialized  data  areas  that  occur  at 
the  end  of  the  program  image  as  part  of  the  resulting  .EXE  file.  To  account  for  the  memory 
space  required  by  these  fields,  the  linker  also  sets  the  MINALLOC  field  in  the  .EXE  file 
header  to  represent  the  data  area  not  written  to  the  file.  MS-DOS  then  uses  the  MINALLOC 
field  to  reallocate  this  missing  space  when  loading  the  program. 
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The  MASM  GROUP  directive 

The  MASM  GROUP  directive  can  also  have  a  strong  impact  on  a  .EXE  program.  However, 
the  GROUP  directive  has  no  effect  on  the  arrangement  of  program  segments  within  mem¬ 
ory.  Rather,  GROUP  associates  program  segments  for  addressing  purposes. 

The  GROUP  directive  has  the  following  syntax: 

grpname  GROUP  segname,segname,segname, ... 

This  directive  causes  the  linker  to  adjust  all  address  references  to  labels  within  any  speci¬ 
fied  segname  to  be  relative  to  the  start  of  the  declared  group.  The  start  of  the  group  is  de¬ 
termined  at  link  time.  The  group  starts  with  whichever  of  the  segments  in  the  GROUP  list 
the  linker  places  lowest  in  memory. 

That  the  GROUP  directive  neither  causes  nor  requires  contiguous  arrangement  of  the 
grouped  segments  creates  some  interesting,  although  not  necessarily  desirable,  possi¬ 
bilities.  For  instance,  it  permits  the  programmer  to  locate  segments  not  belonging  to  the 
declared  group  between  segments  that  do  belong  to  the  group.  The  only  restriction  im¬ 
posed  on  the  declared  group  is  that  the  last  byte  of  the  last  segment  in  the  group  must 
occur  within  64  KB  of  the  start  of  the  group.  Figure  4-7  illustrates  this  type  of  segment 
arrangement: 


•LABEL.C  ► 


64  KB 
m^imum 


Off^t  to 
LABEL.B 


^  LABEL.B  ► 


Offset  to  ^ 

LABEL  C 

-  ^  LABEL^A  ► 

Offset  to 

LABEL  A 

SEGMENT.C 

(listed  with  GROUP  directive) 


SEGMENT.B 

(not  listed  with  GROUP  directive) 


SEGMENT.A 

(listed  with  GROUP  directive) 


Figure  4-7.  Noncontiguous  segments  in  the  same  GROUP. 


Warning:  One  of  the  most  confusing  aspects  of  the  GROUP  directive  relates  to  MASM’s 
OFFSET  operator.  The  GROUP  directive  affects  only  the  offset  addresses  generated  by 
such  direct  addressing  instructions  as 

MOV  AX,FIELD_LABEL 

but  it  has  no  effect  on  immediate  address  values  generated  by  such  instructions  as 

MOV  AX, OFFSET  FIELD-LABEL 
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Using  the  OFFSET  operator  on  labels  contained  within  grouped  segments  requires  the 
following  approach: 

MOV  AX, OFFSET  GROUP-NAME : FIELD-LABEL 

The  programmer  must  explicitly  request  the  offset  from  the  group  base,  because  MASM 
defines  the  result  of  the  OFFSET  operator  to  be  the  offset  of  the  label  from  the  start  of  its 
segment,  not  its  group. 

Structuring  a  small  program  with  SEGMENT  and  GROUP 

Now  that  we  have  analyzed  the  functions  performed  by  the  SEGMENT  and  GROUP  direc¬ 
tives,  we’ll  put  both  directives  to  work  structuring  a  skeleton  program.  The  program, 
shown  in  Figures  4-8, 4-9,  and  4-10,  consists  of  three  source  modules  (MODULE_A, 
MODULE_B,  and  MODULE_C),  each  using  the  following  four  program  segments: 


Segment  Definition 

_TEXT  The  code  or  program  text  segment 

DATA  The  standard  data  segment  containing  preinitialized  data  fields  the  pro¬ 

gram  might  change 

CONST  The  constant  data  segment  containing  constant  data  fields  the  program 

will  not  change 

_BSS  The  “block  storage  segment/space”  segment  containing  uninitialized  data 

fields* 


*  Programmers  familiar  with  the  IBM  1620/1630  or  CDC  6000  and  Cyber  assemblers  may  recognize  BSS  as 
“block  started  at  symbol,”  which  reflects  an  equally  appropriate,  although  somewhat  more  elaborate,  defini¬ 
tion  of  the  abbreviation.  Other  common  translations  of  BSS,  such  as  “blank  static  storage,”  misrepresent  the 
segment  name,  because  blanking  of  BSS  segments  does  not  occur — the  memory  contains  undetermined 
values  when  the  program  begins  execution. 

/Source  Module  MODULE_A 

/Predeclare  all  segments  to  force  the  linker's  segment  ordering  ♦♦**♦♦**♦♦♦*♦* 


-TEXT 

-TEXT 

SEGMENT 

ENDS 

BYTE 

PUBLIC 

' CODE ' 

-DATA 

-DATA 

SEGMENT 

ENDS 

WORD 

PUBLIC 

•DATA' 

CONST 

CONST 

SEGMENT 

ENDS 

WORD 

PUBLIC 

' CONST 

-BSS 

-BSS 

SEGMENT 

ENDS 

WORD 

PUBLIC 

'BSS* 

Figure  4-8.  Structuring  a  .EXE program:  MODULE_A.  (more) 
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STACK  SEGMENT  PARA  STACK  'STACK’ 

STACK  ENDS 

DGROUP  GROUP  -DATA, CONST, _BSS, STACK 

; Constant  declarations  ******************************************************* 
CONST  SEGMENT  WORD  PUBLIC  'CONST' 

CONST_FIELD_A  DB  'Constant  A*  /declare  a  MODULE— A  constant 

CONST  ENDS 

/Preinitialized  data  fields  ************************************************** 
-DATA  SEGMENT  WORD  PUBLIC  'DATA' 

DATA-FIELD-A  DB  'Data  A'  /declare  a  MODULE-A  preinitialized  field 

-DATA  ENDS 

/Uninitialized  data  fields  ***********************************************:ii:tii** 
-BSS  SEGMENT  WORD  PUBLIC  'BSS' 

BSS-FIELD-A  DB  5  DUP(?)  /declare  a  MODULE-A  uninitialized  field 

-BSS  ENDS 


/  Program  text  *******’l'=l'*’l'’l'**SH3|«**5|!*******************5|C********S|t!)t**!»5!|C***5H**5|C***!|C 


-TEXT 

SEGMENT 

BYTE  PUBLIC  'CODE' 

ASSUME 

CS :-TEXT, DS : DGROUP,  ES 

EXTRN 

PROC-B : NEAR 

EXTRN 

PROC-C : NEAR 

PROC-A 

PROC 

NEAR 

CALL 

PROC-B 

CALL 

PROC_C 

MOV 

AX, 4C00H 

INT 

21H 

NOTHING, SS : NOTHING 

/label  is  in  —TEXT  segment  (NEAR) 
/label  is  in  —TEXT  segment  (NEAR) 

/call  into  MODULE-B 
/call  into  MODULE-C 

/terminate  (MS-DOS  2.0  or  later  only) 


PROC_A  ENDP 


-TEXT  ENDS 

Figure  4-8.  Continued.  (more) 
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; Stack  *********************************************************************** 

STACK  SEGMENT  PARA  STACK  'STACK* 

DW  128  DUP(?)  /declare  some  space  to  use  as  stack 

STACK-BASE  LABEL  WORD 

STACK  ENDS 

END  PROC_A  /declare  PROC_A  as  entry  point 

Figure  4-8.  Continued. 


/Source  Module  MODULE_B 

/Constant  declarations  ******************************************************* 

CONST  SEGMENT  WORD  PUBLIC  'CONST* 

CONST_FIELD_B  DB  'Constant  B'  /declare  a  MODULE_B  constant 

CONST  ENDS 

/Preinitialized  data  fields  ♦*♦♦♦♦♦♦♦♦♦♦♦♦♦**♦♦♦♦****♦♦*♦**♦♦*♦♦*♦♦♦*♦♦♦***♦♦* 

-DATA  SEGMENT  WORD  PUBLIC  'DATA* 

DATA_FIELD_B  DB  'Data  B*  /declare  a  MODULE_B  preinitialized  field 

-DATA  ENDS 

/Uninitialized  data  fields  *********♦♦♦♦♦♦***************♦*♦*****♦*♦*♦**♦**♦♦* 

_BSS  SEGMENT  WORD  PUBLIC  'BSS* 

BSS_FIELD_B  DB  5  DUP(?)  /declare  a  MODULE_B  uninitialized  field 

-BSS  ENDS 

/Program  text  ***********♦♦*♦**♦♦♦*♦♦♦***♦♦**♦*******♦*♦****************♦***♦♦ 
DGROUP  GROUP  -DATA, CONST, _BSS 

-TEXT  SEGMENT  BYTE  PUBLIC  'CODE' 

ASSUME  CS : -TEXT , DS : DGROUP , ES : NOTHING, SS : NOTHING 

Figure  4-9.  Structuring  a  .EXE program:  MODULE^B.  (more) 
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PUBLIC  PROC_B  /reference  in  MODULE_A 

PROC_B  PROC  NEAR 

RET 

PROC_B  ENDP 

-TEXT  ENDS 

END 

Figure  4-9.  Continued. 


/Source  Module  MODULE_C 

/Constant  declarations  ******************************************************* 

CONST  SEGMENT  WORD  PUBLIC  'CONST' 

CONST-FIELD-C  DB  'Constant  C  /declare  a  MODULE_C  constant 

CONST  ENDS 

/Preinitialized  data  fields 
-DATA  SEGMENT  WORD  PUBLIC  'DATA' 

DATA_FIELD_C  DB  'Data  C  /declare  a  MODULE_C  preinitialized  field 

-DATA  ENDS 

/Uninitialized  data  fields  *****♦**♦♦**♦♦*♦*♦♦♦♦**♦****♦♦**♦*♦**********♦**♦** 

-BSS  SEGMENT  WORD  PUBLIC  'BSS' 

BSS— FIELD— C  DB  5  DUP{?)  /declare  a  MODULE— C  uninitialized  field 

-BSS  ENDS 

/Program  text  **************************************************************** 
DGROUP  GROUP  -DATA, CONST, _BSS 
-TEXT  SEGMENT  BYTE  PUBLIC  'CODE' 

ASSUME  CS :-TEXT, DS : DGROUP, ES : NOTHING, SS : NOTHING 

Figure  4-10.  Structuring  a  .EXE program:  MODULE^C.  (more) 
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PUBLIC  PROC_C  /referenced  in  MODULE_A 

PROC_C  PROC  NEAR 

RET 

PROC_C  ENDP 

_TEXT  ENDS 

END 

Figure  4-10.  Continued. 

This  example  creates  a  small  memory  model  program  image,  so  the  linked  program  can 
have  only  a  single  code  segment  and  a  single  data  segment — the  simplest  standard  form 
of  a  .EXE  program.  See  Using  Microsoft’s  Contemporary  Memory  Models  below. 

In  addition  to  declaring  the  four  segments  already  discussed,  MODULE_  A  declares  a 
STACK  segment  in  which  to  define  a  block  of  memory  for  use  as  the  program’s  stack  and 
also  defines  the  linking  order  of  the  five  segments.  Defining  the  linking  order  leaves  the 
programmer  free  to  declare  the  segments  in  any  order  when  defining  the  segment  con¬ 
tents — a  necessity  because  the  assembler  has  difficulty  assembling  programs  that  use 
forward  references. 

With  Microsoft’s  MASM  and  LINK  on  the  same  disk  with  the  .ASM  files,  the  following  com¬ 
mands  can  be  made  into  a  batch  file: 

MASM  STRUCA; 

MASM  STRUCB; 

MASM  STRUCC; 

LINK  STRUCA+STRUCB+STRUCC/M; 

These  commands  will  assemble  and  link  all  the  .ASM  files  listed,  producing  the  memory 
map  report  file  STRUCA.MAP  shown  in  Figure  4-11. 


start  Stop  Length  Name  Class 

OOOOOH  OOOOCH  OOOODH  _TEXT  CODE 

OOOOEH  0001 FH  0001 2H  _DATA  DATA 

00020H  0003DH  0001  EH  CONST  CONST 

0003EH  0004EH  0001 1H  _BSS  BSS 

00050H  001 4FH  001 OOH  STACK  STACK 


Origin  Group 
0000:0  DGROUP 

Address  Publics  by  Name 

0000:000b  PR0C_B 

0000:000C  PROC_C 

Figure  4-11.  Structuring  a  .EXE program:  memory  map  report.  (more) 
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Address  Publics  by  Value 

0000:000B  PROC_B 

0000:000c  PR0C_C 

Program  entry  point  at  0000:0000 

Figure  4-11.  Continued. 

The  above  memory  map  report  represents  the  memory  diagram  shown  in  Figure  4-12. 

Absolute 
address 

00150H  ^ 

00050H  ^ 

0004FH  ► 

0004AH  ► 

00049H  ^ 

00044H  ^ 

00043H  ^ 

0003EH  ^ 

00034H  ^ 

0002AH  ^ 

00020H  ^ 

OOOIAH  ^ 

00014H  ^ 

OOOOEH  ^ 

OOOODH  ^ 

OOOOCH  ^ 

DGROUP  OOOOBH  ^ 
addressing  ^  OOOOOH  ^ 
base 

Figure  4-12.  Structure  of  the  sample  .EXE  program. 

Using  Microsoft’s  contemporary  memory  models 

Now  that  we’ve  analyzed  the  various  aspects  of  designing  assembly-language  .EXE  pro¬ 
grams,  we  can  look  at  how  Microsoft’s  high-level-language  compilers  create  .EXE  pro¬ 
grams  from  high-level-language  source  files.  Even  assembly-language  programmers  will 
find  this  discussion  of  interest  and  should  seriously  consider  using  the  five  standard 
memory  models  outlined  here. 

This  discussion  is  based  on  the  Microsoft  C  Compiler  version  4.0,  which,  along  with  the 
Microsoft  FORTRAN  Compiler  version  4.0,  incorporates  the  most  contemporary  code 
generator  currently  available.  These  newer  compilers  generate  code  based  on  three  to  five 
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of  the  following  standard  programmer-selectable  program  structures,  referred  to  as  mem¬ 
ory  models.  The  discussion  of  each  of  these  memory  models  will  center  on  the  model’s 
use  with  the  Microsoft  C  Compiler  and  will  close  with  comments  regarding  any  differences 
for  the  Microsoft  FORTRAN  Compiler. 

Small  (C  compiler  switch /AS)  This  model,  the  default,  includes  only  a  single  code  seg¬ 
ment  and  a  single  data  segment.  All  code  must  fit  within  64  KB,  and  all  data  must  fit  within 
an  additional  64  KB.  Most  C  program  designs  fall  into  this  category.  Data  can  exceed  the 
64  KB  limit  only  if  the  far  and  huge  attributes  are  used,  forcing  the  compiler  to  use  far 
addressing,  and  the  linker  to  place  far  and  huge  data  items  into  separate  segments.  The 
data-size-threshold  switch  described  for  the  compact  model  is  ignored  by  the  Microsoft  C 
Compiler  when  used  with  a  small  model.  The  C  compiler  uses  the  default  segment  name 
_TEXT  for  all  code  and  the  default  segment  name  _DATA  for  all  non-far/huge  data. 
Microsoft  FORTRAN  programs  can  generate  a  semblance  of  this  model  only  by  using  the 
/NM  (name  module)  and  /AM  (medium  model)  compiler  switches  in  combination  with  the 
near  attribute  on  all  subprogram  declarations. 

Medium  (C  and  FORTRAN  compiler  switch /AM)  This  model  includes  only  a  single  data 
segment  but  breaks  the  code  into  multiple  code  segments.  All  data  must  fit  within  64  KB, 
but  the  64  KB  restriction  on  code  size  applies  only  on  a  module-by-module  basis.  Data  can 
exceed  the  64  KB  limit  only  if  the  far  and  huge  attributes  are  used,  forcing  the  compiler  to 
use  far  addressing,  and  the  linker  to  place  far  and  huge  data  items  into  separate  segments. 
The  data-size-threshold  switch  described  for  the  compact  model  is  ignored  by  the 
Microsoft  C  Compiler  when  used  with  a  medium  model.  The  compiler  uses  the  default  seg¬ 
ment  name  _DATA  for  all  non-far/huge  data  and  the  template  module  JXEXT  to  create 
names  for  all  code  segments.  The  module  element  of  module  JTEXT  indicates  where  the 
compiler  is  to  substitute  the  name  of  the  source  module.  For  example,  if  the  source  module 
HELPFUNC.C  is  compiled  using  the  medium  model,  the  compiler  creates  the  code  seg¬ 
ment  HELPFUNC^TEXT.  The  Microsoft  FORTRAN  Compiler  version  4.0  directly  supports 
the  medium  model. 

Compact  (C  compiler  switch /AC)  This  model  includes  only  a  single  code  segment  but 
breaks  the  data  into  multiple  data  segments.  All  code  must  fit  within  64  KB,  but  the  data  is 
allowed  to  consume  all  the  remaining  available  memory.  The  Microsoft  C  Compiler’s  op¬ 
tional  data-size-threshold  switch  (/Gt)  controls  the  placement  of  the  larger  data  items  into 
additional  data  segments,  leaving  the  smaller  items  in  the  default  segment  for  faster  access. 
Individual  data  items  within  the  program  cannot  exceed  64  KB  under  the  compact  model 
without  being  explicitly  declared  huge.  The  compiler  uses  the  default  segment  name 
_TEXT  for  all  code  segments  and  the  template  module#_DKEK  to  create  names  for  all  data 
segments.  The  module  element  indicates  where  the  compiler  is  to  substitute  the  source 
module’s  name;  the  #  element  represents  a  digit  that  the  compiler  changes  for  each  addi¬ 
tional  data  segment  required  to  hold  the  module’s  data.  The  compiler  starts  with  the  digit  5 
and  counts  up.  For  example,  if  the  name  of  the  source  module  is  HELPFUNC.C,  the  com¬ 
piler  names  the  first  data  segment  HELPFUNC5_DATA.  FORTRAN  programs  can  generate 
a  semblance  of  this  model  only  by  using  the  /NM  (name  module)  and  /AL  (large  model) 
compiler  switches  in  combination  with  the  near  attribute  on  all  subprogram  declarations. 
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Large  (C  and  FORTRAN  compiler  switch /AL)  This  model  creates  multiple  code  and  data 
segments.  The  compiler  treats  data  in  the  same  manner  as  it  does  for  the  compact  model 
and  treats  code  in  the  same  manner  as  it  does  for  the  medium  model.  The  Microsoft 
FORTRAN  Compiler  version  4.0  directly  supports  the  large  model. 

Huge  (C  and  FORTRAN  compiler  switch /AH)  Allocation  of  segments  under  the  huge 
model  follows  the  same  rules  as  for  the  large  model.  The  difference  is  that  individual  data 
items  can  exceed  64  KB.  Under  the  huge  model,  the  compiler  generates  the  necessary 
code  to  index  arrays  or  adjust  pointers  across  segment  boundaries,  effectively  transforming 
the  microprocessor’s  segment-addressed  memory  into  linear-addressed  memory.  This 
makes  the  huge  model  especially  useful  for  porting  a  program  originally  written  for  a  pro¬ 
cessor  that  used  linear  addressing.  The  speed  penalties  the  program  pays  in  exchange  for 
this  addressing  freedom  require  serious  consideration.  If  the  program  actually  contains 
any  data  structures  exceeding  64  KB,  it  probably  contains  only  a  few.  In  that  case,  it  is  best 
to  avoid  using  the  huge  model  by  explicitly  declaring  those  few  data  items  as  huge  using 
the  huge  keyword  within  the  source  module.  This  prevents  penalizing  all  the  non-huge 
items  with  extra  addressing  math.  The  Microsoft  FORTRAN  Compiler  version  4.0  directly 
supports  the  huge  model. 

Figure  4-13  shows  an  example  of  the  segment  arrangement  created  by  a  large/huge  model 
program.  The  example  assumes  two  source  modules:  MSCA.C  and  MSCB.C.  Each  source 
module  specifies  enough  data  to  cause  the  compiler  to  create  two  extra  data  segments  for 
that  module.  The  diagram  does  not  show  all  the  various  segments  that  occur  as  a  result  of 
linking  with  the  run-time  library  or  as  a  result  of  compiling  with  the  intention  of  using  the 
CodeView  debugger. 


Groups  Classes  Segments 


STACK 

STACK 

A  SMCLH:  Program  stack 

BSS 

c_common 

◄  SM:  All  uninitialized  global  items,  CLH:  Empty 

DGROUP 

_BSS 

A  SMCLH:  All  uninitialized  non-far/huge  items 

CONST 

CONST 

A  SMCLH:  Constants  (floating  point  constraints,  segment  addresses,  etc.) 

DATA 

_DATA 

4  SMCLH:  All  items  that  don't  end  up  anywhere  else 

FAR.BSS 

FAR_BSS 

A  SM:  Nonexistent,  CLH:  All  uninitialized  global  items 

MSCB6_DATA 

A  From  MSCB  only:  SM:  Far/huge  items,  CLH:  Items  larger  than  threshold 

FAR_DATA 

MSCB5_DATA 

A  From  MSCB  only:  SM:  Far/huge  items,  CLH:  Items  larger  than  threshold 

MSCA6_DATA 

A  From  MSCA  only:  SM:  Far/huge  items,  CLH:  Items  larger  than  threshold 

MSCA5_DATA 

A  From  MSCA  only:  SM:  Far/huge  items,  CLH:  Items  larger  than  threshold 

TEXT 

A  SC:  All  code,  MLH:  Run-time  library  code  only 

CODE 

MSCB.TEXT 

◄  SC:  Nonexistent,  MLH:  MSCB.C  Code 

MSCA.TEXT 

A  SC:  Nonexistent,  MLH:  MSCA.C  Code 

S  =  Small  model  L  =  Large  model 

M  =  Medium  model  H  =  Huge  model 
C  =  Compact  model 


Figure  4-13.  General  structure  of  a  Microsoft  C program. 
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Note  that  if  the  program  declares  an  extremely  large  number  of  small  data  items,  it  can 
exceed  the  64  KB  size  limit  on  the  default  data  segment  (_DATA)  regardless  of  the  memory 
model  specified.  This  occurs  because  the  data  items  all  fall  below  the  data-size-threshold 
limit  (compiler  /Gt  switch),  causing  the  compiler  to  place  them  in  the  _DATA  segment. 
Lowering  the  data  size  threshold  or  explicitly  using  the  far  attribute  within  the  source 
modules  eliminates  this  problem. 

Modifying  the  .EXE  file  header 

With  most  of  its  language  compilers,  Microsoft  supplies  a  utility  program  called  EXEMOD. 
See  PROGRAMMING  UTILITIES:  exemod.  This  utility  allows  the  programmer  to  display 
and  modify  certain  fields  contained  within  the  .EXE  file  header.  Following  are  the  header 
fields  EXEMOD  can  modify  (based  on  EXEMOD  version  4.0): 

MAXALLOC  This  field  can  be  modified  by  using  EXEMOD’s  /MAX  switch.  Because 
EXEMOD  operates  on  .EXE  files  that  have  already  been  linked,  the  /MAX  switch  can  be 
used  to  modify  the  MAXALLOC  field  in  existing  .EXE  programs  that  contain  the  default 
MAXALLOC  value  of  FFFFH,  provided  the  programs  do  not  rely  on  MS-DOS’s  allocating 
all  free  memory  to  them.  EXEMOD’s  /MAX  switch  functions  in  an  identical  manner  to 
LINK’S  /CPARMAXALLOC  switch. 

MINALLOC  This  field  can  be  modified  by  using  EXEMOD’s  /MIN  switch.  Unlike  the  case 
with  the  MAXALLOC  field,  most  programs  do  not  have  an  arbitrary  value  for  MINALLOC. 
MINALLOC  normally  represents  uninitialized  memory  and  stack  space  the  linker  has  com¬ 
pressed  out  of  the  .EXE  file,  so  a  programmer  should  never  reduce  the  MINALLOC  value 
within  a  .EXE  program  written  by  someone  else.  If  a  program  requires  some  minimum 
amount  of  extra  dynamic  memory  in  addition  to  any  static  fields,  MINALLOC  can  be  in¬ 
creased  to  ensure  that  the  program  will  have  this  extra  memory  before  receiving  control.  If 
this  is  done,  the  program  will  not  have  to  verify  that  MS-DOS  allocated  enough  memory  to 
meet  program  needs.  Of  course,  the  same  result  can  be  achieved  without  EXEMOD  by 
declaring  this  minimum  extra  memory  as  an  uninitialized  field  at  the  end  of  the  program. 

Initial  SP  Value  This  field  can  be  modified  by  using  the  /STACK  switch  to  increase  or 
decrease  the  size  of  a  program’s  stack.  However,  modifying  the  initial  SP  value  for  pro¬ 
grams  developed  using  Microsoft  language  compiler  versions  earlier  than  the  following 
may  cause  the  programs  to  fail:  C  version  3.0,  Pascal  version  3-3,  and  FORTRAN  version 
3.3.  Other  language  compilers  may  have  the  same  restriction.  The  /STACK  switch  can  also 
be  used  with  programs  developed  using  MASM,  provided  the  stack  space  is  linked  at  the 
end  of  the  program,  but  it  would  probably  be  wise  to  change  the  size  of  the  STACK  seg¬ 
ment  declaration  within  the  program  instead.  The  linker  also  provides  a  /STACK  switch 
that  performs  the  same  purpose. 

Note:  With  the  /H  switch  set,  EXEMOD  displays  the  current  values  of  the  fields  within 
the  .EXE  header.  This  switch  should  not  be  used  with  the  other  switches.  EXEMOD  also 
displays  field  values  if  no  switches  are  used. 
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Warning:  EXEMOD  also  functions  correctly  when  used  with  packed  .EXE  files  created 
using  EXEPACK  or  the  /EXEPACK  linker  switch.  However,  it  is  important  to  use  the 
EXEMOD  version  shipped  with  the  linker  or  EXEPACK  utility.  Possible  future  changes  in 
the  packing  method  may  result  in  incompatibilities  between  EXEMOD  and  nonassociated 
linker/EXEPACK  versions. 

Patching  the  .EXE  program  using  DEBUG 

Every  experienced  programmer  knows  that  programs  always  seem  to  have  at  least  one 
unspotted  error.  If  a  program  has  been  distributed  to  other  users,  the  programmer  will 
probably  need  to  provide  those  users  with  corrections  when  such  bugs  come  to  light.  One 
inexpensive  updating  approach  used  by  many  large  companies  consists  of  mailing  out 
single-page  instructions  explaining  how  the  user  can  patch  the  program  to  correct  the 
problem. 

Program  patching  usually  involves  loading  the  program  file  into  the  DEBUG  utility  sup¬ 
plied  with  MS-DOS,  storing  new  bytes  into  the  program  image,  and  then  saving  the  pro¬ 
gram  file  back  to  disk.  Unfortunately,  DEBUG  cannot  load  a  .EXE  program  into  memory 
and  then  save  it  back  to  disk  in  .EXE  format.  The  programmer  must  trick  DEBUG  into 
patching  .EXE  program  files,  using  the  procedure  outlined  below.  See  PROGRAMMING 
UTILITIES:  debug. 

Note:  Users  should  be  reminded  to  make  backup  copies  of  their  program  before  attempt¬ 
ing  the  patching  procedure. 

1.  Rename  the  .EXE  file  using  a  filename  extension  that  does  not  have  special  meaning 
for  DEBUG.  (Avoid  .EXE,  .COM,  and  .HEX.)  For  instance,  MYPROG.BIN  serves  well  as 
a  temporary  new  name  for  MYPROG.EXE  because  DEBUG  does  not  recognize  a  file 
with  a  .BIN  extension  as  anything  special.  DEBUG  will  load  the  entire  image  of 
MYPROG.BIN,  including  the  .EXE  header  and  relocation  table,  into  memory  starting 
at  offset  lOOH  within  a  .COM-style  program  segment  (as  discussed  previously). 

2.  Locate  the  area  within  the  load  module  section  of  the  .EXE  file  image  that  requires 
patching.  The  previous  discussion  of  the  .EXE  file  image,  together  with  compiler/ 
assembler  listings  and  linker  memory  map  reports,  provides  the  information  neces¬ 
sary  to  locate  the  error  within  the  .EXE  file  image.  DEBUG  loads  the  file  image  start¬ 
ing  at  offset  lOOH  within  a  .COM-style  program  segment,  so  the  programmer  must 
compensate  for  this  offset  when  calculating  addresses  within  the  file  image.  Also,  the 
compiler  listings  and  linker  memory  map  reports  provide  addresses  relative  to  the 
start  of  the  program  image  within  the  .EXE  file,  not  relative  to  the  start  of  the  file 
itself.  Therefore,  the  programmer  must  first  check  the  information  contained  in  the 
.EXE  file  header  to  determine  where  the  load  module  (the  program’s  image)  starts 
within  the  file. 

3.  Use  DEBUG’S  E  (Enter  Data)  or  A  (Assemble  Machine  Instructions)  command  to 
insert  the  corrections.  (Normally,  patch  instructions  to  users  would  simply  give  an 
address  at  which  the  user  should  apply  the  patch.  The  user  need  not  know  how  to 
determine  the  address.) 

4.  After  the  patch  has  been  applied,  simply  issue  the  DEBUG  W  (Write  File  or  Sectors) 
command  to  write  the  corrected  image  back  to  disk  under  the  same  filename,  pro¬ 
vided  the  patch  has  not  increased  the  size  of  the  program.  If  program  size  has 
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increased,  first  change  the  appropriate  size  fields  in  the  .EXE  header  at  the  start  of  the 
file  and  use  the  DEBUG  R  (Display  or  Modify  Registers)  command  to  modify  the  BX 
and  CX  registers  so  that  they  contain  the  file  image’s  new  size.  Then  use  the  W  com¬ 
mand  to  write  the  image  back  to  disk  under  the  same  name. 

5.  Use  the  DEBUG  Q  (Quit)  command  to  return  to  MS-DOS  command  level,  and  then 
rename  the  file  to  the  original  .EXE  filename  extension. 

.EXE  summary 

To  summarize,  the  .EXE  program  and  file  structures  provide  considerable  flexibility  in  the 
design  of  programs,  providing  the  programmer  with  the  necessary  freedom  to  produce 
large-scale  applications.  Programs  written  using  Microsoft’s  high-level-language  compilers 
have  access  to  five  standardized  program  structure  models  (small,  medium,  compact, 
large,  and  huge).  These  standardized  models  are  excellent  examples  of  ways  to  structure 
assembly-language  programs. 


The  .COM  Program 

The  majority  of  differences  between  .COM  and  .EXE  programs  exist  because  .COM 
program  files  are  not  prefaced  by  header  information.  Therefore,  .COM  programs  do  not 
benefit  from  the  features  the  .EXE  header  provides. 

The  absence  of  a  header  leaves  MS-DOS  with  no  way  of  knowing  how  much  memory  the 
.COM  program  requires  in  addition  to  the  size  of  the  program’s  image.  Therefore,  MS-DOS 
must  always  allocate  the  largest  free  block  of  memory  to  the  .COM  program,  regardless  of 
the  program’s  true  memory  requirements.  As  was  discussed  for  .EXE  programs,  this  allo¬ 
cation  of  the  largest  block  of  free  memory  usually  results  in  MS-DOS’s  allocating  all 
remaining  free  memory — an  action  that  can  cause  problems  for  multitasking  supervisor 
programs. 

The  .EXE  program  header  also  includes  the  direct  segment  address  relocation  pointer 
table.  Because  they  lack  this  table,  .COM  programs  cannot  make  address  references  to  the 
labels  specified  in  SEGMENT  directives,  with  the  exception  of  SEGMENT  AT  address 
directives.  If  a  .COM  program  did  make  these  references,  MS-DOS  would  have  no  way  of 
adjusting  the  addresses  to  correspond  to  the  actual  segment  address  into  which  MS-DOS 
loaded  the  program.  See  Creating  the  .COM  Program  below. 

The  .COM  program  structure  exists  primarily  to  support  the  vast  number  of  CP/M  pro¬ 
grams  ported  to  MS-DOS.  Currently,  .COM  programs  are  most  often  used  to  avoid  adding 
the  512  bytes  or  more  of  .EXE  header  information  onto  small,  simple  programs  that  often 
do  not  exceed  512  bytes  by  themselves. 

The  .COM  program  structure  has  another  advantage:  Its  memory  organization  places  the 
PSP  within  the  same  address  segment  as  the  rest  of  the  program.  Thus,  it  is  easier  to  access 
fields  within  the  PSP  in  .COM  programs. 
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Giving  control  to  the  .COM  program 

After  allocating  the  largest  block  of  free  memory  to  the  .COM  program,  MS-DOS  builds 
a  PSP  in  the  lowest  lOOH  bytes  of  the  block.  No  difference  exists  between  the  PSP  MS-DOS 
builds  for  .COM  programs  and  the  PSP  it  builds  for  .EXE  programs.  Also  with  .EXE  pro¬ 
grams,  MS-DOS  determines  the  initial  values  for  the  AL  and  AH  registers  at  this  time  and 
then  loads  the  entire  .COM-file  image  into  memory  immediately  following  the  PSP. 

Because  .COM  files  have  no  file-size  header  fields,  MS-DOS  relies  on  the  size  recorded  in 
the  disk  directory  to  determine  the  size  of  the  program  image.  It  loads  the  program  exactly 
as  it  appears  in  the  file,  without  checking  the  file’s  contents. 

MS-DOS  then  sets  the  DS,  ES,  and  SS  segment  registers  to  point  to  the  start  of  the  PSP.  If 
able  to  allocate  at  least  64  KB  to  the  program,  MS-DOS  sets  the  SP  register  to  offset  FFFFH 
+  1  (OOOOH)  to  establish  an  initial  stack;  if  less  than  64  KB  are  available  for  allocation  to  the 
program,  MS-DOS  sets  the  SP  to  1  byte  past  the  highest  offset  owned  by  the  program.  In 
either  case,  MS-DOS  then  pushes  a  single  word  of  OOOOH  onto  the  program’s  stack  for 
use  in  terminating  the  program. 

Finally,  MS-DOS  transfers  control  to  the  program  by  setting  the  CS  register  to  the  PSP’s 
segment  address  and  the  IP  register  to  OlOOH.  This  means  that  the  program’s  entry  point 
must  exist  at  the  very  start  of  the  program’s  image,  as  shown  in  later  examples. 

Figure  4-14  shows  the  overall  structure  of  a  .COM  program  as  it  receives  control  from 
MS-DOS. 


.COM  program  memory  image 

J 


64  KB* 


◄  IIM)100H 

◄  CS,DS.ES,SS 

*The  SP  and  64  KB  values  are  dependent  upon 
MS-DOS  having  64  KB  or  more  of  memory 
available  to  allocate  to  the  .COM  program 
at  load  time. 

Figure  4-14.  The  .COM  program:  memory  map  diagram  with  register  pointers. 


SP=FFFEH* 


Remaining  free  memory 
within  first  64  KB  allocated 
to  .COM  program 

(provided  a  full  64  KB  was  available) 


.COM  program  image  from  file 


Program  segment  prefix 
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Terminating  the  .COM  program 

A  .COM  program  can  use  all  the  termination  methods  described  for  .EXE  programs  but 
should  still  use  the  MS-DOS  Interrupt  21H  Terminate  Process  with  Return  Code  function 
(4CH)  as  the  preferred  method.  If  the  .COM  program  must  remain  compatible  with  ver¬ 
sions  of  MS-DOS  earlier  than  2.0,  it  can  easily  use  any  of  the  older  termination  methods, 
including  those  described  as  difficult  to  use  from  .EXE  programs,  because  .COM  programs 
execute  with  the  CS  register  pointing  to  the  PSP  as  required  by  these  methods. 

Creating  the  .COM  program 

A  .COM  program  is  created  in  the  same  manner  as  a  .EXE  program  and  then  converted 
using  the  MS-DOS  EXE2BIN  utility.  See  PROGRAMMING  UTILITIES:  exe2bin. 

Certain  restrictions  do  apply  to  .COM  programs,  however.  First,  .COM  programs  cannot 
exceed  64  KB  minus  lOOH  bytes  for  the  PSP  minus  2  bytes  for  the  zero  word  initially 
pushed  on  the  stack. 

Next,  only  a  single  segment — or  at  least  a  single  addressing  group — should  exist  within 
the  program.  The  following  two  examples  show  ways  to  structure  a  .COM  program  to  sat¬ 
isfy  both  this  restriction  and  MASM's  need  to  have  data  fields  precede  program  code  in  the 
source  file. 

COMPROG1.ASM  (Figure  4-15)  declares  only  a  single  segment  iCOMSEG),  so  no  special 
considerations  apply  when  using  the  MASM  OFFSET  operator.  See  The  MASM  GROUP 
Directive  above.  COMPROG2.ASM  (Figure  4-l6)  declares  separate  code  iCSEG)  and  data 
iDSEG)  segments,  which  the  GROUP  directive  ties  into  a  common  addressing  block. 

Thus,  the  programmer  can  declare  data  fields  at  the  start  of  the  source  file  and  have  the 
linker  place  the  data  fields  segment  iDSEG^  after  the  code  segment  iCSEG)  when  it  links 
the  program,  as  discussed  for  the  .EXE  program  structure.  This  second  example  simulates 
the  program  structuring  provided  under  CP/M  by  Microsoft’s  old  Macro-80  (M80)  macro 
assembler  and  Link-80  (L80)  linker.  The  design  also  expands  easily  to  accommodate 
COMMON  or  other  additional  segments. 


COMSEG 

SEGMENT 

BYTE  PUBLIC  'CODE' 

ASSUME 

CS : COMSEG, DS : COMSEG, ES : COMSEG, SS : COMSEG 

ORG 

0100H 

BEGIN: 

JMP 

START  ; skip  over 

data  fields 

; Place 

your  data  fields  here. 

START : 

; Place 

your  program  text  here. 

MOV 

AX,4C00H  /terminate 

(MS-DOS  2.0  ( 

INT 

21H 

COMSEG 

ENDS 

END 

BEGIN 

Figure  4-15.  .  COM  program  with  data  at  start. 
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CSEG 

SEGMENT 

BYTE  PUBLIC  ' 

'CODE'  /establish 

segment  order 

CSEG 

ENDS 

DSEG 

SEGMENT 

BYTE  PUBLIC  ' 

'  DATA ' 

DSEG 

ENDS 

COMGRP 

GROUP 

CSEG, DSEG 

/ establish 

joint  address  base 

DSEG 

SEGMENT 

/Place 

your  data  fields  here, 

DSEG 

ENDS 

CSEG 

SEGMENT 

ASSUME 

CS: COMGRP, DS; 

:  COMGRP , ES : COMGRP , SS : COMGRP 

ORG 

OlOOH 

BEGIN: 

/Place  your  program  text  here.  Remember  to  use 
/OFFSET  COMGRP: LABEL  whenever  you  use  OFFSET. 


MOV 

AX, 4C00H 

/terminate  (MS-DOS  2.0  or  later  only) 

INT 

21H 

CSEG 

ENDS 

END 

BEGIN 

Figure  4-16.  .COM program  with  data  at  end. 

These  examples  demonstrate  other  significant  requirements  for  producing  a  functioning 
.COM  program.  For  instance,  the  ORG  OlOOH  statement  in  both  examples  tells  MASM  to 
start  assembling  the  code  at  offset  lOOH  within  the  encompassing  segment.  This  corre¬ 
sponds  to  MS-DOS’s  transferring  control  to  the  program  at  IP  =  OlOOH.  In  addition,  the 
entry-point  label  (BEGIN)  immediately  follows  the  ORG  statement  and  appears  again  as  a 
parameter  to  the  END  statement.  Together,  these  factors  satisfy  the  requirement  that  .COM 
programs  declare  their  entry  point  at  offset  lOOH.  If  any  factor  is  missing,  the  MS-DOS 
EXE2BIN  utility  will  not  properly  convert  the  .EXE  file  produced  by  the  linker  into  a  .COM 
file.  Specifically,  if  a  .COM  program  declares  an  entry  point  (as  a  parameter  to  the  END 
statement)  that  is  at  neither  offset  OlOOH  nor  offset  OOOOH,  EXE2BIN  rejects  the  .EXE  file 
when  the  programmer  attempts  to  convert  it.  If  the  program  fails  to  declare  an  entry  point 
or  declares  an  entry  point  at  offset  OOOOH,  EXE2BIN  assumes  that  the  .EXE  file  is  to  be 
converted  to  a  binary  image  rather  than  to  a  .COM  image.  When  EXE2BIN  converts  a  .EXE 
file  to  a  non-.COM  binary  file,  it  does  not  strip  the  extra  lOOH  bytes  the  linker  places  in 
front  of  the  code  as  a  result  of  the  ORG  OlOOH  instruction.  Thus,  the  program  actually 
begins  at  offset  200H  when  MS-DOS  loads  it  into  memory,  but  all  the  program’s  address 
references  will  have  been  assembled  and  linked  based  on  the  lOOH  offset.  As  a  result,  the 
program — and  probably  the  rest  of  the  system  as  well — is  likely  to  crash. 

A  .COM  program  also  must  not  contain  direct  segment  address  references  to  any  segments 
that  make  up  the  program.  Thus,  the  .COM  program  cannot  reference  any  segment  labels 
or  reference  any  labels  as  long  (FAR)  pointers.  (This  rule  does  not  prevent  the  program 
from  referencing  segment  labels  declared  using  the  SEGMENT  AT  address  directive.) 
Following  are  various  examples  of  direct  segment  address  references  that  are  not  per¬ 
mitted  as  part  of  .COM  programs: 
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PR0C_J^ 

PR0C_A 

PROC 

ENDP 

CALL 

FAR 

PR0C_A 

;  intersegment 

call 

JMP 

PROC^ 

; intersegment 

jump 

or 

EXTRN 

CALL 

PR0C_A:FAR 

PR0C_A 

; intersegment 

call 

JMP 

PR0C_A 

; intersegment 

jump 

or 

MOV 

AX,SEG  SEG_A 

/segment  address 

DD 

LABELS 

; segment : of f set  pointer 

Finally,  .COM  programs  must  not  declare  any  segments  with  the  STACK  combine  type.  If 
a  program  declares  a  segment  with  the  STACK  combine  type,  the  linker  will  insert  initial 
SS  and  SP  values  into  the  .EXE  file  header,  causing  EXE2BIN  to  reject  the  .EXE  file.  A  .COM 
program  does  not  have  explicitly  declared  stacks,  although  it  can  reserve  space  in  a  non- 
STACK  combine  type  segment  to  which  it  can  initialize  the  SP  register  after  it  receives 
control.  The  absence  of  a  stack  segment  will  cause  the  linker  to  issue  a  harmless  warning 
message. 

When  the  program  is  assembled  and  linked  into  a  .EXE  file,  it  must  be  converted  into  a 
binary  file  with  a  .COM  extension  by  using  the  EXE2BIN  utility  as  shown  in  the  following 
example  for  the  file  YOURPROG.EXE: 

C>EXE2BIN  YOURPROG  YOURPROG.COM  <Enter> 

It  is  not  necessary  to  delete  or  rename  a  .EXE  file  with  the  same  filename  as  the  .COM 
file  before  trying  to  execute  the  .COM  file  as  long  as  both  remain  in  the  same  directory, 
because  MS-DOS’s  order  of  execution  is  .COM  files  first,  then  .EXE  files,  and  finally  .BAT 
files.  However,  the  safest  practice  is  to  delete  a  .EXE  file  immediately  after  converting  it  to 
a  .COM  file  in  case  the  .COM  file  is  later  renamed  or  moved  to  a  different  directory.  If  a 
.EXE  file  designed  for  conversion  to  a  .COM  file  is  executed  by  accident,  it  is  likely  to  crash 
the  system. 

Patching  the  .COM  program  using  DEBUG 

As  discussed  for  .EXE  files,  a  programmer  who  distributes  software  to  users  will  probably 
want  to  send  instructions  on  how  to  patch  in  error  corrections.  This  approach  to  software 
updates  lends  itself  even  better  to  .COM  files  than  it  does  to  .EXE  files. 

For  example,  because  .COM  files  contain  only  the  code  image,  they  need  not  be  renamed 
in  order  to  read  and  write  them  using  DEBUG.  The  user  need  only  be  instructed  on  how  to 
load  the  .COM  file  into  DEBUG,  how  to  patch  the  program,  and  how  to  write  the  patched 
image  back  to  disk.  Calculating  the  addresses  and  patch  values  is  even  easier,  because  no 
header  exists  in  the  .COM  file  image  to  cause  complications.  With  the  preceding  excep¬ 
tions,  the  details  for  patching  .COM  programs  remain  the  same  as  previously  outlined  for 
.EXE  programs. 
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.COM  summary 

To  summarize,  the  .COM  program  and  file  structures  are  a  simpler  but  more  restricted 
approach  to  writing  programs  than  the  .EXE  structure  because  the  programmer  has  only  a 
single  memory  model  from  which  to  choose  (the  .COM  program  segment  model).  Also, 
.COM  program  files  do  not  contain  the  512-byte  (or  more)  header  inherent  to  .EXE  files,  so 
the  .COM  program  structure  is  well  suited  to  small  programs  for  which  adding  512  bytes 
of  header  would  probably  at  least  double  the  file’s  size. 


Summary  of  Differences 

The  following  table  summarizes  the  differences  between  .COM  and  .EXE  programs. 


•COM  program  .EXE  program 


Maximum  size 

65536  bytes  minus  256  bytes 
for  PSP  and  2  bytes  for  stack 

No  limit 

Entry  point 

PSPrOlOOH 

Defined  by  END  statement 

CS  at  entry 

PSP 

Segment  containing  program’s 
entry  point 

IP  at  entry 

OlOOH 

Offset  of  entry  point  within  its 
segment 

DS  at  entry 

PSP 

PSP 

ES  at  entry 

PSP 

PSP 

SS  at  entry 

PSP 

Segment  with  STACK  attribute 

SP  at  entry 

FFFEH  or  top  word  in  available 
memory,  whichever  is  lower 

End  of  segment  defined  with 
STACK  attribute 

Stack  at  entry 

Zero  word 

Initialized  or  uninitialized, 
depending  on  source 

Stack  size 

65536  bytes  minus  256  bytes 
for  PSP  and  size  of  executable 
code  and  data 

Defined  in  segment  with 
STACK  attribute 

Subroutine  calls 

NEAR 

NEAR  or  FAR 

Exit  method 

Interrupt  21H  Function  4CH 
preferred;  NEAR  RET  if 
MS-DOS  versions  1.x 

Interrupt  21H  Function  4CH 
preferred;  indirect  jump 
to  PSPiOOOOH  if  MS-DOS 
versions  1.x 

Size  of  file 

Exact  size  of  program 

Size  of  program  plus  header  (at 
least  512  extra  bytes) 
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Which  format  the  programmer  uses  for  an  application  usually  depends  on  the  program’s 
intended  size,  but  the  decision  can  also  be  influenced  by  a  program’s  need  to  address  mul¬ 
tiple  memory  segments.  Normally,  small  utility  programs  (such  as  CHKDSK  and  FOR¬ 
MAT)  are  designed  as  .COM  programs;  large  programs  (such  as  the  Microsoft  C  Compiler) 
are  designed  as  .EXE  programs.  The  ultimate  decision  is,  of  course,  the  programmer’s. 


Keith  Burgoyne 
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Article  5: 

Character  Device  Input  and  Output 


All  functional  computer  systems  are  composed  of  a  central  processing  unit  (CPU),  some 
memory,  and  peripheral  devices  that  the  CPU  can  use  to  store  data  or  communicate  with 
the  outside  world.  In  MS-DOS  systems,  the  essential  peripheral  devices  are  the  keyboard 
(for  input),  the  display  (for  output),  and  one  or  more  disk  drives  (for  nonvolatile  storage). 
Additional  devices  such  as  printers,  modems,  and  pointing  devices  extend  the  function¬ 
ality  of  the  computer  or  offer  alternative  methods  of  using  the  system. 

MS-DOS  recognizes  two  types  of  devices:  block  devices,  which  are  usually  floppy-disk  or 
fixed-disk  drives;  and  character  devices,  such  as  the  keyboard,  display,  printer,  and  com¬ 
munications  ports. 

The  distinction  between  block  and  character  devices  is  not  always  readily  apparent,  but 
in  general,  block  devices  transfer  information  in  chunks,  or  blocks,  and  character  devices 
move  data  one  character  (usually  1  byte)  at  a  time.  MS-DOS  identifies  each  block  device  by 
a  drive  letter  assigned  when  the  device’s  controlling  software,  the  device  driver,  is  loaded. 
A  character  device,  on  the  other  hand,  is  identified  by  a  logical  name  (similar  to  a  filename 
and  subject  to  many  of  the  same  restrictions)  built  into  its  device  driver.  See  PROGRAM¬ 
MING  IN  THE  MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Installable  Device  Drivers. 


Background  Information 

Versions  1.x  of  MS-DOS,  first  released  for  the  IBM  PC  in  1981,  supported  peripheral  devices 
with  a  fixed  set  of  device  drivers  loaded  during  system  initialization  from  the  hidden  file 
lO.SYS  (or  IBMBIO.COM  with  PC-DOS).  These  versions  of  MS-DOS  offered  application 
programs  a  high  degree  of  input/output  device  independence  by  allowing  character 
devices  to  be  treated  like  files,  but  they  did  not  provide  an  easy  way  to  augment  the  built-in 
set  of  drivers  if  the  user  wished  to  add  a  third-party  peripheral  device  to  the  system. 

With  the  release  of  MS-DOS  version  2,0,  the  hardware  flexibility  of  the  system  was  tremen¬ 
dously  enhanced.  Versions  2.0  and  later  support  installable  device  drivers  that  can  reside  in 
separate  files  on  the  disk  and  can  be  linked  into  the  operating  system  simply  by  adding  a 
DEVICE  directive  to  the  CONFIG.SYS  file  on  the  startup  disk.  See  USER  COMMANDS: 
CONFIG.SYS:  DEVICE.  A  Well-defined  interface  between  installable  drivers  and  the  MS-DOS 
kernel  allows  such  drivers  to  be  written  for  most  types  of  peripheral  devices  without  the 
need  for  modification  to  the  operating  system  itself. 

The  CONFIG.SYS  file  can  contain  a  number  of  different  DEVICE  commands  to  load  sepa¬ 
rate  drivers  for  pointing  devices,  magnetic-tape  drives,  network  interfaces,  and  so  on.  Each 
driver,  in  turn,  is  specialized  for  the  hardware  characteristics  of  the  device  it  supports. 
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When  the  system  is  turned  on  or  restarted,  the  installable  device  drivers  are  added  to  the 
chain,  or  linked  list,  of  default  device  drivers  loaded  from  lO.SYS  during  MS-DOS  initializa¬ 
tion.  Thus,  the  need  for  the  system’s  default  set  of  device  drivers  to  support  a  wide  range  of 
optional  device  types  and  features  at  an  excessive  cost  of  system  memory  is  avoided. 

One  important  distinction  between  block  and  character  devices  is  that  MS-DOS  always 
adds  new  block-device  drivers  to  the  tail  of  the  driver  chain  but  adds  new  character-device 
drivers  to  the  head  of  the  chain.  Thus,  because  MS-DOS  searches  the  chain  sequentially 
and  uses  the  first  driver  it  finds  that  satisfies  its  search  conditions,  any  existing  character- 
device  driver  can  be  superseded  by  simply  installing  another  driver  with  an  identical  logi¬ 
cal  device  name. 

This  article  covers  some  of  the  details  of  working  with  MS-DOS  character  devices:  display¬ 
ing  text,  keyboard  input,  and  other  basic  character  I/O  functions;  the  definition  and  use  of 
standard  input  and  output;  redirection  of  the  default  character  devices;  and  the  use  of  the 
lOCTL  function  (Interrupt  21H  Function  44H)  to  communicate  directly  with  a  character- 
device  driver.  Much  of  the  information  presented  in  this  article  is  applicable  only  to 
MS-DOS  versions  2.0  and  later. 


Accessing  Character  Devices 

Application  programs  can  use  either  of  two  basic  techniques  to  access  character  devices  in 
a  portable  manner  under  MS-DOS.  First,  a  program  can  use  the  handle-type  function  calls 
that  were  added  to  MS-DOS  in  version  2.0.  Alternatively,  a  program  can  use  the  so-called 
“traditional”  character-device  functions  that  were  present  in  versions  1.x  and  have  been 
retained  in  the  operating  system  for  compatibility.  Because  the  handle  functions  are  more 
powerful  and  flexible,  they  are  discussed  first. 

A  handle  is  a  l6-bit  number  returned  by  the  operating  system  whenever  a  file  or  device  is 
opened  or  created  by  passing  a  name  to  MS-DOS  Interrupt  21H  Function  3CH  (Create  File 
with  Handle),  3DH  (Open  File  with  Handle),  5AH  (Create  Temporary  File),  or  5BH  (Create 
New  File).  After  a  handle  is  obtained,  it  can  be  used  with  Interrupt  21H  Function  3FH 
(Read  File  or  Device)  or  Function  40H  (Write  File  or  Device)  to  transfer  data  between  the 
computer’s  memory  and  the  file  or  device. 

During  an  open  or  create  function  call,  MS-DOS  searches  the  device-driver  chain  sequen¬ 
tially  for  a  character  device  with  the  specified  name  (the  extension  is  ignored)  before 
searching  the  disk  directory.  Thus,  a  file  with  the  same  name  as  any  character  device  in  the 
driver  chain — for  example,  the  file  NUL.TXT — cannot  be  created,  nor  can  an  existing  file 
be  accessed  if  a  device  in  the  chain  has  the  same  name. 

The  second  method  for  accessing  character  devices  is  through  the  traditional  MS-DOS 
character  input  and  output  functions.  Interrupt  21H  Functions  OlH  through  OCH.  These 
functions  are  designed  to  communicate  directly  with  the  keyboard,  display,  printer,  and 
serial  port.  Each  of  these  devices  has  its  own  function  or  group  of  functions,  so  neither 
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names  nor  handles  need  be  used.  However,  in  MS-DOS  versions  2.0  and  later,  these  func¬ 
tion  calls  are  translated  within  MS-DOS  to  make  use  of  the  same  routines  that  are  used  by 
the  handle  functions,  so  the  traditional  keyboard  and  display  functions  are  affected  by  I/O 
redirection  and  piping. 

Use  of  either  the  traditional  or  the  handle-based  method  for  character  device  I/O  results 
in  highly  portable  programs  that  can  be  used  on  any  computer  that  runs  MS-DOS.  A  third, 
less  portable  access  method  is  to  use  the  hardware-specific  routines  resident  in  the  read¬ 
only  memory  (ROM)  of  a  specific  computer  (such  as  the  IBM  PC  ROM  BIOS  driver  func¬ 
tions),  and  a  fourth,  definitely  nonportable  approach  is  to  manipulate  the  peripheral 
device’s  adapter  directly,  bypassing  the  system  software  altogether.  Although  these  latter 
hardware-dependent  methods  cannot  be  recommended,  they  are  admittedly  sometimes 
necessary  for  performance  reasons. 


The  Basic  MS-DOS  Character  Devices 

Every  MS-DOS  system  supports  at  least  the  following  set  of  logical  character  devices 
without  the  need  for  any  additional  installable  drivers: 


Device  Meaning 

CON  Keyboard  and  display 

PRN  System  list  device,  usually  a  parallel  port 

AUX  Auxiliary  device,  usually  a  serial  port 

CLOCKS  System  real-time  clock 

NUL  “Bit-bucket”  device 

These  devices  can  be  opened  by  name  or  they  can  be  addressed  through  the  “traditional” 
function  calls;  strings  can  be  read  from  or  written  to  the  devices  according  to  their  capabili¬ 
ties  on  any  MS-DOS  system.  Data  written  to  the  NUL  device  is  discarded;  reads  from  the 
NUL  device  always  return  an  end-of-file  condition. 

PC-DOS  and  compatible  implementations  of  MS-DOS  typically  also  support  the  following 
logical  character-device  names: 


Device  Meaning 

COMl  First  serial  communications  port 
COM2  Second  serial  communications  port 

LPTl  First  parallel  printer  port 

LPT  2  Second  parallel  printer  port 

LPT3  Third  parallel  printer  port 
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In  such  systems,  PRN  is  an  alias  for  LPTl  and  AUX  is  an  alias  for  COMl.  The  MODE  com¬ 
mand  can  be  used  to  redirect  an  LPT  device  to  another  device.  See  USER  COMMANDS: 

MODE. 

As  previously  mentioned,  any  of  these  default  character-device  drivers  can  be  superseded 
by  a  user-installed  device  driver — for  example,  one  that  offers  enhanced  functionality  or 
changes  the  device’s  apparent  characteristics.  One  frequently  used  alternative  character- 
device  driver  is  ANSI.SYS,  which  replaces  the  standard  MS-DOS  CON  device  driver  and 
allows  ANSI  escape  sequences  to  be  used  to  perform  tasks  such  as  clearing  the  screen, 
controlling  the  cursor  position,  and  selecting  character  attributes.  See  USER  COMMANDS: 

ANSI.SYS. 

The  standard  devices 

Under  MS-DOS  versions  2.0  and  later,  each  program  owns  five  previously  opened  handles 
for  character  devices  (referred  to  as  the  standard  devices)  when  it  begins  executing.  These 
handles  can  be  used  for  input  and  output  operations  without  further  preliminaries.  The 
five  standard  devices  and  their  associated  handles  are 


standard  Device  Name  Handle  Default  Assignment 


Standard  input  istdin)  0  CON 

Standard  output  istdouf)  1  CON 

Standard  error  istderr)  2  CON 

Standard  auxiliary  istdawd  3  AUX 

Standard  printer  istdprn)  4  PRN 


The  standard  input  and  standard  output  handles  are  especially  important  because  they  are 
subject  to  I/O  redirection.  Although  these  handles  are  associated  by  default  with  the  CON 
device  so  that  read  and  write  operations  are  implemented  using  the  keyboard  and  video 
display,  the  user  can  associate  the  handles  with  other  character  devices  or  with  files  by 
using  redirection  parameters  in  a  program’s  command  line: 


Redirection  Result 

<  file  Causes  read  operations  from  standard  input  to  obtain  data  from  file. 

>  file  Causes  data  written  to  standard  output  to  be  placed  in  file. 

»  file  Causes  data  written  to  standard  output  to  be  appended  to  file, 

pi  !  p2  Causes  data  written  to  standard  output  by  program  pi  to  appear  as  the 

standard  input  of  program  p2. 

This  ability  to  redirect  I/O  adds  great  flexibility  and  power  to  the  system.  For  example, 
programs  ordinarily  controlled  by  keyboard  entries  can  be  run  with  “scripts”  from  files, 
the  output  of  a  program  can  be  captured  in  a  file  or  on  a  printer  for  later  inspection,  and 
general-purpose  programs  (filters)  can  be  written  that  process  text  streams  without  regard 
to  the  text’s  origin  or  destination.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT: 
Customizing  ms-dos:  Writing  MS-DOS  Filters. 
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Ordinarily,  an  application  program  is  not  aware  that  its  input  or  output  has  been  redi¬ 
rected,  although  a  write  operation  to  standard  output  will  fail  unexpectedly  if  standard 
output  was  redirected  to  a  disk  file  and  the  disk  is  full.  An  application  can  check  for  the 
existence  of  I/O  redirection  with  an  lOCTL  (Interrupt  21H  Function  44H)  call,  but  it  can¬ 
not  obtain  any  information  about  the  destination  of  the  redirected  handle  except  whether 
it  is  associated  with  a  character  device  or  with  a  file. 

Raw  versus  cooked  mode 

MS-DOS  associates  each  handle  for  a  character  device  with  a  mode  that  determines  how 
I/O  requests  directed  to  that  handle  are  treated.  When  a  handle  is  in  raw  mode,  characters 
are  passed  between  the  application  program  and  the  device  driver  without  any  filtering  or 
buffering  by  MS-DOS.  When  a  handle  is  in  cooked  mode,  MS-DOS  buffers  any  dka  that  is 
read  from  or  written  to  the  device  and  takes  special  actions  when  certain  characters  are 
detected. 

During  cooked  mode  input,  MS-DOS  obtains  characters  from  the  device  driver  one  at  a 
time,  checking  each  character  for  a  Control-C.  The  characters  are  assembled  into  a  string 
within  an  internal  MS-DOS  buffer.  The  input  operation  is  terminated  when  a  carriage 
return  (ODH)  or  an  end-of-file  mark  (lAH)  is  received  or  when  the  number  of  characters 
requested  by  the  application  have  been  accumulated.  If  the  source  is  standard  input,  lone 
linefeed  characters  are  translated  to  carriage-return/linefeed  pairs.  The  string  is  then 
copied  from  the  internal  MS-DOS  buffer  to  the  application  program’s  buffer,  and  control 
returns  to  the  application  program. 

During  cooked  mode  output,  MS-DOS  transfers  the  characters  in  the  application  pro¬ 
gram’s  output  buffer  to  the  device  driver  one  at  a  time,  checking  after  each  character  for 
a  Control-C  pending  at  the  keyboard.  If  the  destination  is  standard  output  and  standard 
output  has  not  been  redirected,  tabs  are  expanded  to  spaces  using  eight-column  tab  stops. 
Output  is  terminated  when  the  requested  number  of  characters  have  been  written  or  when 
an  end-of-file  mark  (lAH)  is  encountered  in  the  output  string. 

In  contrast,  during  raw  mode  input  or  output,  data  is  transferred  directly  between  the 
application  program’s  buffer  and  the  device  driver.  Special  characters  such  as  carriage 
return  and  the  end-of-file  mark  are  ignored,  and  the  exact  number  of  characters  in  the  ap¬ 
plication  program’s  request  are  always  read  or  written.  MS-DOS  does  not  break  the  strings 
into  single-character  calls  to  the  device  driver  and  does  not  check  the  keyboard  buffer  for 
Control-C  entries  during  the  I/O  operation.  Finally,  characters  read  from  standard  input 
in  raw  mode  are  not  echoed  to  standard  output. 

As  might  be  expected  from  the  preceding  description,  raw  mode  input  or  output  is  usu¬ 
ally  much  faster  than  cooked  mode  input  or  output,  because  each  character  is  not  being 
individually  processed  by  the  MS-DOS  kernel.  Raw  mode  also  allows  programs  to  read 
characters  from  the  keyboard  buffer  that  would  otherwise  be  trapped  by  MS-DOS  (for 
example,  Control-C,  Control-P,  and  Control-S).  (If  BREAK  is  on,  MS-DOS  will  still  check  for 
Control-C  entries  during  other  function  calls,  such  as  disk  operations,  and  transfer  control 
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to  the  Control-C  exception  handler  if  a  Control-C  is  detected.)  A  program  can  use  the 
MS-DOS  lOCTL  Get  and  Set  Device  Data  services  (Interrupt  21H  Function  44H  Subfunc¬ 
tions  OOH  and  OlH)  to  set  the  mode  for  a  character-device  handle.  See  lOCTL  below. 

Ordinarily,  raw  or  cooked  mode  is  strictly  an  attribute  of  a  specific  handle  that  was 
obtained  from  a  previous  open  operation  and  affects  only  the  I/O  operations  requested 
by  the  program  that  owns  the  handle.  However,  when  a  program  uses  lOCTL  to  select  raw 
or  cooked  mode  for  one  of  the  standard  device  handles,  the  selection  has  a  global  effect 
on  the  behavior  of  the  system  because  those  handles  are  never  closed.  Thus,  some  of  the 
“traditional”  keyboard  input  functions  might  behave  in  unexpected  ways.  Consequently, 
programs  that  change  the  mode  on  a  standard  device  handle  should  save  the  handle’s 
mgde  at  entry  and  restore  it  before  performing  a  final  exit  to  MS-DOS,  so  that  the  opera¬ 
tion  of  COMMAND.COM  and  other  applications  will  not  be  disturbed.  Such  programs 
should  also  incorporate  custom  critical  error  and  Control-C  exception  handlers  so  that  the 
programs  cannot  be  terminated  unexpectedly.  See  PROGRAMMING  IN  THE  MS-DOS 
ENVIRONMENT:  Customizing  ms-dos:  Exception  Handlers. 

The  keyboard 

Among  the  MS-DOS  Interrupt  21H  functions  are  two  methods  of  checking  for  and  receiv¬ 
ing  input  from  the  keyboard:  the  traditional  method,  which  uses  MS-DOS  character  input 
Functions  OlH,  06H,  07H,  OSH,  OAH,  OBH,  and  OCH  (Table  5-1);  and  the  handle  method, 
which  uses  Function  3FH.  Each  of  these  methods  has  its  own  advantages  and  disadvan¬ 
tages.  See  SYSTEM  CALLS. 


Table  5-1*  Traditional  MS-DOS  Character  Input  Functions. 


Function 

Name 

Read  Multiple 
Characters 

Echo 

Ctrl-C 

Check 

OlH 

Character  Input  with  Echo 

No 

Yes 

Yes 

06H 

Direct  Console  I/O 

No 

No 

No 

07H 

Unfiltered  Character  Input 
Without  Echo 

No 

No 

No 

OSH 

Character  Input  Without  Echo 

No 

No 

Yes 

OAH 

Buffered  Keyboard  Input 

Yes 

Yes 

Yes 

OBH 

Check  Keyboard  Status 

No 

No 

Yes 

OCH 

Flush  Buffer,  Read  Keyboard 

* 

* 

* 

•  Varies  depending  on  function  (from  above)  called  in  the  AL  register. 


The  first  four  traditional  keyboard  input  calls  are  really  very  similar.  They  all  return  a  char¬ 
acter  in  the  AL  register;  they  differ  mainly  in  whether  they  echo  that  character  to  the  dis¬ 
play  and  whether  they  are  sensitive  to  interruption  by  the  user’s  entry  of  a  Control-C.  Both 
Functions  06H  and  OBH  can  be  used  to  test  keyboard  status  (that  is,  whether  a  key  has 
been  pressed  and  is  waiting  to  be  read  by  the  program);  Function  OBH  is  simpler  to  use, 
but  Function  06H  is  immune  to  Control-C  entries. 
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Function  OAH  is  used  to  read  a  “buffered  line”  from  the  user,  meaning  that  an  entire  line  is 
accepted  by  MS-DOS  before  control  returns  to  the  program.  The  line  is  terminated  when 
the  user  presses  the  Enter  key  or  when  the  maximum  number  of  characters  (to  255)  speci¬ 
fied  by  the  program  have  been  received.  While  entry  of  the  line  is  in  progress,  the  usual 
editing  keys  (such  as  the  left  and  right  arrow  keys  and  the  function  keys  on  IBM  PCs  and 
compatibles)  are  active;  only  the  final,  edited  line  is  delivered  to  the  requesting  program. 

Function  OCH  allows  a  program  to  flush  the  type-ahead  buffer  before  accepting  input. 

This  capability  is  important  for  occasions  when  a  prompt  must  be  displayed  unexpectedly 
(such  as  when  a  critical  error  occurs)  and  the  user  could  not  have  typed  ahead  a  valid 
response.  This  function  should  also  be  used  when  the  user  is  being  prompted  for  a  critical 
decision  (such  as  whether  to  erase  a  file),  to  prevent  a  character  that  was  previously 
pressed  by  accident  from  triggering  an  irrecoverable  operation.  Function  OCH  is  unusual 
in  that  it  is  called  with  the  number  of  one  of  the  other  keyboard  input  functions  in  register 
AL.  After  any  pending  input  has  been  discarded.  Function  OCH  simply  transfers  to  the 
other  specified  input  function;  thus,  its  other  parameters  (if  any)  depend  on  the  function 
that  ultimately  will  be  executed. 

The  primary  disadvantage  of  the  traditional  function  calls  is  that  they  handle  redirected 
input  poorly.  If  standard  input  has  been  redirected  to  a  file,  no  way  exists  for  a  program 
calling  the  traditional  input  functions  to  detect  that  the  end  of  the  file  has  been  reached — 
the  input  function  will  simply  wait  forever,  and  the  system  will  appear  to  hang. 

A  program  that  wishes  to  use  handle-based  I/O  to  get  input  from  the  keyboard  must  use 
the  MS-DOS  Read  File  or  Device  service.  Interrupt  21H  Function  3FH.  Ordinarily,  the  pro¬ 
gram  can  employ  the  predefined  handle  for  standard  input  (0),  which  does  not  need  to  be 
opened  and  which  allows  the  program’s  input  to  be  redirected  by  the  user  to  another  file 
or  device.  If  the  program  needs  to  circumvent  redirection  and  ensure  that  its  input  is  from 
the  keyboard,  it  can  open  the  CON  device  with  Interrupt  21H  Function  3DH  and  use  the 
handle  obtained  from  that  open  operation  instead  of  the  standard  input  handle. 

A  program  using  the  handle  functions  to  read  the  keyboard  can  control  the  echoing  of 
characters  and  sensitivity  to  Control-C  entries  by  selecting  raw  or  cooked  mode  with  the 
lOCTL  Get  and  Set  Device  Data  services  (default  =  cooked  mode).  To  test  the  keyboard 
status,  the  program  can  either  issue  an  lOCTL  Check  Input  Status  call  (Interrupt  21H  Func¬ 
tion  44H  Subfunction  06H)  or  use  the  traditional  Check  Keyboard  Status  call  (Interrupt 
21H  Function  OBH). 

The  primary  advantages  of  the  handle  method  for  keyboard  input  are  its  symmetry  with 
file  operations  and  its  graceful  handling  of  redirected  input.  The  handle  function  also 
allows  strings  as  long  as  65535  bytes  to  be  requested;  the  traditional  Buffered  Keyboard 
Input  function  allows  a  maximum  of  255  characters  to  be  read  at  a  time.  This  considera¬ 
tion  is  important  for  programs  that  are  frequently  used  with  redirected  input  and  output 
(such  as  filters),  because  reading  and  writing  larger  blocks  of  data  from  files  results  in 
more  efficient  operation.  The  only  real  disadvantage  to  the  handle  method  is  that  it  is 
limited  to  MS-DOS  versions  2.0  and  later  (although  this  is  no  longer  a  significant 
restriction). 
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Role  of  the  ROM  BIOS 

When  a  key  is  pressed  on  the  keyboard  of  an  IBM  PC  or  compatible,  it  generates  a  hard¬ 
ware  interrupt  (09H)  that  is  serviced  by  a  routine  in  the  ROM  BIOS.  The  ROM  BIOS  inter¬ 
rupt  handler  reads  I/O  ports  assigned  to  the  keyboard  controller  and  translates  the  key’s 
scan  code  into  an  ASCII  character  code.  The  result  of  this  translation  depends  on  the  cur¬ 
rent  state  of  the  NumLock  and  CapsLock  toggles,  as  well  as  on  whether  the  Shift,  Control, 
or  Alt  key  is  being  held  down.  (The  ROM  BIOS  maintains  a  keyboard  flags  byte  at  address 
0000:0417H  that  gives  the  current  status  of  each  of  these  modifier  keys.) 

After  translation,  both  the  scan  code  and  the  ASCII  code  are  placed  in  the  ROM  BIOS’s 
32-byte  (l6-character)  keyboard  input  buffer.  In  the  case  of  “extended”  keys  such  as  the 
function  keys  or  arrow  keys,  the  ASCII  code  is  a  zero  byte  and  the  scan  code  carries  all  the 
information.  The  keyboard  buffer  is  arranged  as  a  circular,  or  ring,  buffer  and  is  managed 
as  a  first-in/first-out  queue.  Because  of  the  method  used  to  determine  when  the  buffer  is 
empty,  one  position  in  the  buffer  is  always  wasted;  the  maximum  number  of  characters 
that  can  be  held  in  the  buffer  is  therefore  15.  Keys  pressed  when  the  buffer  is  full  are 
discarded  and  a  warning  beep  is  sounded. 

The  ROM  BIOS  provides  an  additional  module,  invoked  by  software  Interrupt  16H,  that 
allows  programs  to  test  keyboard  status,  determine  whether  characters  are  waiting  in  the 
type-ahead  buffer,  and  remove  characters  from  the  buffer.  See  Appendix  O:  IBM  PC  BIOS 
Calls.  Its  use  by  application  programs  should  ordinarily  be  avoided,  however,  to  prevent 
introducing  unnecessary  hardware  dependence. 

On  IBM  PCs  and  compatibles,  the  keyboard  input  portion  of  the  CON  driver  in  the 
BIOS  is  a  simple  sequence  of  code  that  calls  ROM  BIOS  Interrupt  16H  to  do  the  hardware- 
dependent  work.  Thus,  calls  to  MS-DOS  for  keyboard  input  by  an  application  program  are 
subject  to  two  layers  of  translation:  The  Interrupt  21H  function  call  is  converted  by  the 
MS-DOS  kernel  to  calls  to  the  CON  driver,  which  in  turn  remaps  the  request  onto  a  ROM 
BIOS  call  that  obtains  the  character. 

Keyboard  prograoiming  examples 

Example:  Use  the  ROM  BIOS  keyboard  driver  to  read  a  character  from  the  keyboard.  The 
character  is  not  echoed  to  the  display. 

iTiov  ah,  OOh  ;  subfunction  OOH  =  read  character 

int  1 6h  ;  transfer  to  ROM  BIOS 

;  now  AH  =  scan  code,  AL  =  character 

Example:  Use  the  MS-DOS  traditional  keyboard  input  function  to  read  a  character  from 
the  keyboard.  The  character  is  not  echoed  to  the  display.  The  input  can  be  interrupted 
with  a  Ctrl-C  keystroke. 

mov  ah,08h  ;  function  OSH  =  character  input 

;  without  echo 

int  21 h  ;  transfer  to  MS-DOS 

;  now  AL  =  character 
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Example:  Use  the  MS-DOS  traditional  Buffered  Keyboard  Input  function  to  read  an  entire 
line  from  the  keyboard,  specifying  a  maximum  line  length  of  80  characters.  All  editing 
keys  are  active  during  entry,  and  the  input  is  echoed  to  the  display. 


kbuf  db  80 

db  0 

db  80  dup  (0) 


;  maximum  length  of  read 
;  actual  length  of  read 
;  keyboard  input  goes  here 


mov  dx,seg  kbuf 

mov  ds ,  dx 

mov  dx, offset  kbuf 

mov  ah,0ah 

int  21  h 


set  DS:DX  =  address  of 
keyboard  input  buffer 

function  OAH  =  read  buffered  line 
transfer  to  MS-DOS 
terminated  by  a  carriage  return, 
and  kbuf+1  =  length  of  input, 
not  including  the  carriage  return 


Example:  Use  the  MS-DOS  handle-based  Read  File  or  Device  function  and  the  standard 
input  handle  to  read  an  entire  line  from  the  keyboard,  specifying  a  maximum  line  length 
of  80  characters.  All  editing  keys  are  active  during  entry,  and  the  input  is  echoed  to  the  dis¬ 
play.  (The  input  will  not  terminate  on  a  carriage  return  as  expected  if  standard  input  is  in 
raw  mode.) 

kbuf  db 


mov 

mov 

mov 

mov 

mov 

mov 

int 

jc 


The  display 

The  output  half  of  the  MS-DOS  logical  character  device  CON  is  the  video  display.  On  IBM 
PCs  and  compatibles,  the  video  display  is  an  “option”  of  sorts  that  comes  in  several  forms. 
IBM  has  introduced  five  video  subsystems  that  support  different  types  of  displays:  the 
Monochrome  Display  Adapter  (MDA),  the  Color/Graphics  Adapter  (CGA),  the  Enhanced 
Graphics  Adapter  (EGA),  the  Video  Graphics  Array  (VGA),  and  the  Multi-Color  Graphics 
Array  (MCGA).  Other,  non-IBM-compatible  video  subsystems  in  common  use  include  the 
Hercules  Graphics  Card  and  its  variants  that  support  downloadable  fonts. 


80  dup  (0) 


;  buffer  for  keyboard  input 


dx,seg  kbuf 
ds,  dx 

dx, offset  kbuf 

cx,  80 

bx,  0 

ah, 3fh 

21h 

error 


set  DS:DX  =  address  of 
keyboard  input  buffer 

CX  =  maximum  length  of  input 
standard  input  handle  =  0 
function  3FH  =  read  file/device 
transfer  to  MS-DOS 
jump  if  function  failed 
otherwise  AX  =  actual 
length  of  keyboard  input, 
including  carriage-return  and 
linefeed,  and  the  data  is 
in  the  buffer  'kbuf 
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Two  portable  techniques  exist  for  writing  text  to  the  video  display  with  MS-DOS  function 
calls.  The  traditional  method  is  supported  by  Interrupt  21H  Functions  02H  (Character  Out¬ 
put),  06H  (Direct  Console  I/O),  and  09H  (Display  String).  The  handle  method  is  supported 
by  Function  40H  (Write  File  or  Device)  and  is  available  only  in  MS-DOS  versions  2.0  and 
later.  See  SYSTEM  CALLS:  Interrupt  21h:  Functions  02H,  06H,  09H,  40H.  All  these  calls 
treat  the  display  essentially  as  a  “glass  teletype”  and  do  not  support  bit-mapped  graphics. 

Traditional  Functions  02H  and  06H  are  similar.  Both  are  called  with  the  character  to  be 
displayed  in  the  DL  register;  they  differ  in  that  Function  02H  is  sensitive  to  interruption  by 
the  user’s  entry  of  a  Control-C,  whereas  Function  06H  is  immune  to  Control-C  but  cannot 
be  used  to  output  the  character  OFFH  (ASCII  rubout).  Both  calls  check  specifically  for  car¬ 
riage  return  (ODH),  linefeed  (OAH),  and  backspace  (OSH)  characters  and  take  the  appro¬ 
priate  action  if  these  characters  are  detected. 

Because  making  individual  calls  to  MS-DOS  for  each  character  to  be  displayed  is  inefficient 
and  slow,  the  traditional  Display  String  function  (09H)  is  generally  used  in  preference  to 
Functions  02H  and  06H.  Function  09H  is  called  with  the  address  of  a  string  that  is  termi¬ 
nated  with  a  dollar-sign  character  ($);  it  displays  the  entire  string  in  one  operation,  regard¬ 
less  of  its  length.  The  string  can  contain  embedded  control  characters  such  as  carriage 
return  and  linefeed. 

To  use  the  handle  method  for  screen  display,  programs  must  call  the  MS-DOS  Write  File 
or  Device  service.  Interrupt  21H  Function  40H.  Ordinarily,  a  program  should  use  the  pre¬ 
defined  handle  for  standard  output  (1)  to  send  text  to  the  screen,  so  that  any  redirection 
requested  by  the  user  on  the  program’s  command  line  will  be  honored.  If  the  program 
needs  to  circumvent  redirection  and  ensure  that  its  output  goes  to  the  screen,  it  can  either 
use  the  predefined  handle  for  standard  error  (2)  or  explicitly  open  the  CON  device  with 
Interrupt  21H  Function  3DH  and  use  the  resulting  handle  for  its  write  operations. 

The  handle  technique  for  displaying  text  has  several  advantages  over  the  traditional 
calls.  First,  the  length  of  the  string  to  be  displayed  is  passed  as  an  explicit  parameter,  so 
the  string  need  not  contain  a  special  terminating  character  and  the  $  character  can  be  dis¬ 
played  as  part  of  the  string.  Second,  the  traditional  calls  are  translated  to  handle  calls 
inside  MS-DOS,  so  the  handle  calls  have  less  internal  overhead  and  are  generally  faster. 
Finally,  use  of  the  handle  Write  File  or  Device  function  to  display  text  is  symmetric  with 
the  methods  the  program  must  use  to  access  its  files.  In  short,  the  traditional  functions 
should  be  avoided  unless  the  program  must  be  capable  of  running  under  MS-DOS  ver¬ 
sions  1.x. 

Controlling  the  screen 

One  of  the  deficiencies  of  the  standard  MS-DOS  CON  device  driver  is  the  lack  of  screen- 
control  capabilities.  The  default  CON  driver  has  no  built-in  routines  to  support  cursor 
placement,  screen  clearing,  display  mode  selection,  and  so  on. 

In  MS-DOS  versions  2.0  and  later,  an  optional  replacement  CON  driver  is  supplied  in  the 
file  ANSI.SYS.  This  driver  contains  most  of  the  screen-control  capabilities  needed  by  text- 
oriented  application  programs.  The  driver  is  installed  by  adding  a  DEVICE  directive  to  the 
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CONFIG.SYS  file  and  restarting  the  system.  When  ANSI.SYS  is  active,  a  program  can 
position  the  cursor,  inquire  about  the  current  cursor  position,  select  foreground  and 
background  colors,  and  clear  the  current  line  or  the  entire  screen  by  sending  an  escape 
sequence  consisting  of  the  ASCII  Esc  character  (IBH)  followed  by  various  function- 
specific  parameters  to  the  standard  output  device.  See  USER  COMMANDS:  ansi.sys. 

Programs  that  use  the  ANSI.SYS  capabilities  for  screen  control  are  portable  to  any  MS-DOS 
implementation  that  contains  the  ANSI.SYS  driver.  Programs  that  seek  improved  perfor¬ 
mance  by  calling  the  ROM  BIOS  video  driver  or  by  assuming  direct  control  of  the  hard¬ 
ware  are  necessarily  less  portable  and  usually  require  modification  when  new  PC  models 
or  video  subsystems  are  released. 

Role  of  the  ROM  BIOS 

The  video  subsystems  in  IBM  PCs  and  compatibles  use  a  hybrid  of  memory-mapped  and 
port-addressed  I/O.  A  range  of  the  machine’s  memory  addresses  is  typically  reserved  for  a 
video  refresh  buffer  that  holds  the  character  codes  and  attributes  to  be  displayed  on  the 
screen;  the  cursor  position,  display  mode,  palettes,  and  similar  global  display  char¬ 
acteristics  are  governed  by  writing  control  values  to  specific  I/O  ports. 

The  ROM  BIOS  of  IBM  PCs  and  compatibles  contains  a  primitive  driver  for  the  MDA,  CGA, 
EGA,  VGA,  and  MCGA  video  subsystems.  This  driver  supports  the  following  functions: 

•  Read  or  write  characters  with  attributes  at  any  screen  position. 

•  Query  or  set  the  cursor  position. 

•  Clear  or  scroll  an  arbitrary  portion  of  the  screen. 

•  Select  palette,  background,  foreground,  and  border  colors. 

•  Query  or  set  the  display  mode  (40-column  text,  80-column  text,  all-points-addressable 
graphics,  and  so  on). 

•  Read  or  write  a  pixel  at  any  screen  coordinate. 

These  functions  are  invoked  by  a  program  through  software  Interrupt  lOH.  See  Appendix 
O:  IBM  PC  BIOS  Calls.  In  PC-DOS-compatible  implementations  of  MS-DOS,  the  display 
portions  of  the  MS-DOS  CON  and  ANSI.SYS  drivers  use  these  ROM  BIOS  routines.  Video 
subsystems  that  are  not  IBM  compatible  either  must  contain  their  own  ROM  BIOS  or  must 
be  used  with  an  installable  device  driver  that  captures  Interrupt  lOH  and  provides  appro¬ 
priate  support  functions. 

Text-only  application  programs  should  avoid  use  of  the  ROM  BIOS  functions  or  direct 
access  to  the  hardware  whenever  possible,  to  ensure  maximum  portability  between 
MS-DOS  systems.  However,  because  the  MS-DOS  CON  driver  contains  no  support  for  bit¬ 
mapped  graphics,  graphically  oriented  applications  usually  must  resort  to  direct  control 
of  the  video  adapter  and  its  refresh  buffer  for  speed  and  precision. 
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Display  programming  examples 

Example:  Use  the  ROM  BIOS  Interrupt  lOH  function  to  write  an  asterisk  character  to  the 
display  in  text  mode.  (In  graphics  mode,  BL  must  also  be  set  to  the  desired  foreground 
color.) 


mov 

ah, Oeh 

;  subfunction  OEH  =  write  character 

;  in  teletype  mode 

mov 

al, 

;  AL  =  character  to  display 

mov 

bh,0 

;  select  display  page  0 

int 

lOh 

;  transfer  to  ROM  BIOS  video  driver 

Example:  Use  the  MS-DOS  traditional  function  to  write  an  asterisk  character  to  the  dis- 

play.  If  the  user’s 

entry  of  a  Control-C  is  detected  during  the  output  and  standard  output  is 

in  cooked  mode,  MS-DOS  calls  the  Control-C  exception  handler  whose  address  is  found 

in  the  vector  for  Interrupt  23H. 

mov 

ah,02h 

;  function  02H  =  display  character 

mov 

dl, 

;  DL  =  character  to  display 

int 

21h 

;  transfer  to  MS-DOS 

Example:  Use  the  MS-DOS  traditional  function  to  write  a  string  to  the  display.  The  output 
is  terminated  by  the  $  character  and  can  be  interrupted  when  the  user  enters  a  Control-C  if 
standard  output  is  in  cooked  mode. 

msg  db 

’This  is  a  test 

message', '$* 

mov 

dx, seg  msg 

;  DS:DX  =  address  of  text 

mov 

ds,  dx 

;  to  display 

mov 

dx, offset  msg 

mov 

ah,09h 

;  function  09H  =  display  string 

int 

21h 

;  transfer  to  MS-DOS 

Example:  Use  the  MS-DOS  handle-based  Write  File  or  Device  function  and  the  predefined 
handle  for  standard  output  to  write  a  string  to  the  display.  Output  can  be  interrupted  by  the 
user’s  entry  of  a  Control-C  if  standard  output  is  in  cooked  mode. 

msg  db 

'This  is  a  test 

message' 

msg_len  equ 

$-msg 

mov 

dx, seg  msg 

;  DS:DX  =  address  of  text 

mov 

ds,  dx 

;  to  display 

mov 

dx, offset  msg 

mov 

cx, msg_len 

;  CX  =  length  of  text 

mov 

bx,1 

;  BX  =  handle  for  standard  output 

mov 

ah, 40h 

;  function  40H  =  write  file/device 

int 

21h 

;  transfer  to  MS-DOS 
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The  serial  communications  ports 

Through  version  3.2,  MS-DOS  has  built-in  support  for  two  serial  communications  ports, 
identified  as  COMl  and  COM2,  by  means  of  three  drivers  named  AUX,  COMl,  and  COM2. 
(AUX  is  ordinarily  an  alias  for  COMl.) 

The  traditional  MS-DOS  method  of  reading  from  and  writing  to  the  serial  ports  is  through 
Interrupt  21H  Function  03H  for  AUX  input  and  Function  04H  for  AUX  output.  In  MS-DOS 
versions  2.0  and  later,  the  handle-based  Read  File  or  Device  and  Write  File  or  Device  func¬ 
tions  (Interrupt  21H  Functions  3FH  and  40H)  can  be  used  to  read  from  or  write  to  the  aux¬ 
iliary  device.  A  program  can  use  the  predefined  handle  for  the  standard  auxiliary  device 
(3)  with  Functions  3FH  and  40H,  or  it  can  explicitly  open  the  COMl  or  COM2  devices  with 
Interrupt  21H  Function  3DH  and  use  the  handle  obtained  from  that  open  operation  to 
perform  read  and  write  operations. 

MS-DOS  support  for  the  serial  communications  port  is  inadequate  in  several  respects  for 
high-performance  serial  I/O  applications.  First,  MS-DOS  provides  no  portable  way  to  test 
for  the  existence  or  the  status  of  a  particular  serial  port  in  a  system;  if  a  program  “opens” 
COM2  and  writes  data  to  it  and  the  physical  COM2  adapter  is  not  present  in  the  system,  the 
program  may  simply  hang.  Similarly,  if  the  serial  port  exists  but  no  character  has  been 
received  and  the  program  attempts  to  read  a  character,  the  program  will  hang  until  one  is 
available;  there  is  no  traditional  function  call  to  check  if  a  character  is  waiting  as  there  is 
for  the  keyboard. 

MS-DOS  also  provides  no  portable  method  to  initialize  the  communications  adapter  to  a 
particular  baud  rate,  word  length,  and  parity.  An  application  must  resort  to  ROM  BIOS 
calls,  manipulate  the  hardware  directly,  or  rely  on  the  user  to  configure  the  port  properly 
with  the  MODE  command  before  running  the  application  that  uses  it.  The  default  settings 
for  the  serial  port  on  PC-DOS-compatible  systems  are  2400  baud,  no  parity,  1  stop  bit,  and 
8  databits.  See  USER  COMMANDS:  mode. 

A  more  serious  problem  with  the  default  MS-DOS  auxiliary  device  driver  in  IBM  PCs  and 
compatibles,  however,  is  that  it  is  not  interrupt  driven.  Accordingly,  when  baud  rates  above 
1200  are  selected,  characters  can  be  lost  during  time-consuming  operations  performed  by 
the  drivers  for  other  devices,  such  as  clearing  the  screen  or  reading  or  writing  a  floppy-disk 
sector.  Because  the  MS-DOS  AUX  device  driver  typically  relies  on  the  ROM  BIOS  serial  port 
driver  (accessed  through  software  Interrupt  14H)  and  because  the  ROM  BIOS  driver  is  not 
interrupt  driven  either,  bypassing  MS-DOS  and  calling  the  ROM  BIOS  functions  does  not 
usually  improve  matters. 

Because  of  all  the  problems  just  described,  telecommunications  application  programs 
commonly  take  over  complete  control  of  the  serial  port  and  supply  their  own  interrupt 
handler  and  internal  buffering  for  character  read  and  write  operations.  See  PROGRAM¬ 
MING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Interrupt-Driven 
Communications. 
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Serial  port  programming  examples 

Example:  Use  the  ROM  BIOS  serial  port  driver  to  write  a  string  to  COMl. 


msg 

db 

'This  is  a  test  message 

msg_len 

equ 

$-msg 

mov 

bx,seg  msg 

DS:BX  =  address  of  message 

mov 

ds,bx 

mov 

bx, offset  msg 

mov 

cx,msg_len 

CX  =  length  of  message 

mov 

dx,  0 

DX  =  0  for  COMl 

L 1  :  mov 

al, [bx] 

get  next  character  into  AL 

mov 

ah,01h 

subfunction  01 H  =  output 

int 

14h 

transfer  to  ROM  BIOS 

inc 

bx 

bump  pointer  to  output  string 

loop 

LI 

and  loop  until  all  chars,  sent 

Example:  Use  the  MS-DOS  traditional  function  for  auxiliary  device  output  to  write  a  string 
toCOMl. 

msg  db 

'This  is  a  test  n 

ties  sage* 

msg_len  equ 

$-msg 

mov 

bx,seg  msg 

;  set  DS:BX  =  address  of  message 

mov 

ds,bx 

mov 

bx, offset  msg 

mov 

cx,msg_len 

;  set  CX  = 

length  of  message 

LI  :  mov 

dl, [bx] 

;  get  next 

character  into  DL 

mov 

ah,04h 

;  function 

04H  =  auxiliary  output 

int 

21h 

;  transfer 

to  MS-DOS 

inc 

bx 

;  bump  pointer  to  output  string 

loop 

LI 

;  and  loop 

until  all  chars,  sent 

Example:  Use  the  MS-DOS  handle-based  Write  File  or  Device  function  and  the  predefined 
handle  for  the  standard  auxiliary  device  to  write  a  string  to  COMl. 

msg  db 

'This  is  a  test 

message' 

msg_len  equ 

$-msg 

mov 

dx,seg  msg 

;  DS:DX  =  address  of  message 

mov 

ds,dx 

mov 

dx, offset  msg 

mov 

cx,msg_len 

;  CX  =  length  of  message 

mov 

bx,  3 

;  BX  =  handle  for  standard  aux. 

mov 

ah, 40h 

;  function  40H  =  write  file/device 

int 

21h 

;  transfer  to  MS-DOS 

jc 

error 

;  jump  if  write  operation  failed 
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The  parallel  port  and  printer 

Most  MS-DOS  implementations  contain  device  drivers  for  four  printer  devices:  LPTl,  LPT2, 
LPT3,  and  PRN.  PRN  is  ordinarily  an  alias  for  LPTl  and  refers  to  the  first  parallel  output 
port  in  the  system.  To  provide  for  list  devices  that  do  not  have  a  parallel  interface,  the  LPT 
devices  can  be  individually  redirected  with  the  MODE  command  to  one  of  the  serial  com¬ 
munications  ports.  See  USER  COMMANDS:  mode. 

As  with  the  keyboard,  the  display,  and  the  serial  port,  MS-DOS  allows  the  printer  to  be 
accessed  with  either  traditional  or  handle-based  function  calls.  The  traditional  function 
call  is  Interrupt  21H  Function  05H,  which  accepts  a  character  in  DL  and  sends  it  to  the 
physical  device  currently  assigned  to  logical  device  name  LPTl. 

A  program  can  perform  handle-based  output  to  the  printer  with  Interrupt  21H  Function 
40H  (Write  File  or  Device).  The  predefined  handle  for  the  standard  printer  (4)  can  be  used 
to  send  strings  to  logical  device  LPTl.  Alternatively,  the  program  can  issue  an  open  oper¬ 
ation  for  a  specific  printer  device  with  Interrupt  21H  Function  3DH  and  use  the  handle 
obtained  from  that  open  operation  with  Function  40H.  This  latter  method  also  allows 
more  than  one  printer  to  be  used  at  a  time  from  the  same  program. 

Because  the  parallel  ports  are  assumed  to  be  output  only,  no  traditional  call  exists  for 
input  from  the  parallel  port.  In  addition,  no  portable  method  exists  to  test  printer  port 
status  under  MS-DOS;  programs  that  wish  to  avoid  sending  a  character  to  the  printer 
adapter  when  it  is  not  ready  or  not  physically  present  in  the  system  must  test  the  adapter’s 
status  by  making  a  call  to  the  ROM  BIOS  printer  driver  (by  means  of  software  Interrupt 
17H;  5^^  Appendix  O:  IBM  PC  BIOS  Calls)  or  by  accessing  the  hardware  directly. 

Parallel  port  programming  examples 

Example:  Use  the  ROM  BIOS  printer  driver  to  send  a  string  to  the  first  parallel  printer  port. 


msg 

db 

'This  is  a  test 

message ' 

msg_len 

equ 

$-msg 

mov 

bx,seg  msg 

;  DS:BX  =  address  of  message 

mov 

ds,bx 

mov 

bx, offset  msg 

mov 

cx, msg_len 

;  CX  =  length  of  message 

mov 

dx,  0 

;  DX  =  0  for  LPTl 

LI  : 

mov 

al, [bx] 

;  get  next  character  into  AL 

mov 

ah, OOh 

;  subfunction  OOH  =  output 

int 

17h 

;  transfer  to  ROM  BIOS 

inc 

bx 

;  bump  pointer  to  output  string 

loop 

LI 

;  and  loop  until  all  chars,  sent 
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Example:  Use  the  traditional  MS-DOS  function  call  to  send  a  string  to  the  first  parallel 
printer  port. 


msg 

db 

'This  is  a  test  message 

msg_len 

equ 

$-msg 

mov 

bx,seg  msg 

;  DS:BX  =  address  of  message 

mov 

ds,bx 

mov 

bx, offset  msg 

mov 

cx,msg_len 

/  CX  =  length  of  message 

LI  :  mov 

dl, [bx] 

;  get  next  character  into  DL 

mov 

ah, 05h 

;  function  OSH  =  printer  output 

int 

21h 

;  transfer  to  MS-DOS 

inc 

bx 

;  bump  pointer  to  output  string 

loop 

LI 

;  and  loop  until  all  chars,  sent 

Example:  Use  the  handle-based  MS-DOS  Write  File  or  Device  call  and  the  predefined 
handle  for  the  standard  printer  to  send  a  string  to  the  system  list  device. 

msg  db 

'This  is  a  test 

message ' 

msg_len  equ 

$-msg 

mov 

dx,seg  msg 

;  DS:DX  =  address  of  message 

mov 

ds,  dx 

mov 

dx, offset  msg 

mov 

cx,msg_len 

;  CX  =  length  of  message 

mov 

bx,  4 

;  BX  =  handle  for  standard 

printer 

mov 

ah, 40h 

;  function  40H  =  write  file/device 

int 

21h 

;  transfer  to  MS-DOS 

jc 

error 

;  jump  if  write  operation 

failed 

lOCTL 

In  versions  2.0  and  later,  MS-DOS  has  provided  applications  with  the  ability  to  communi¬ 
cate  directly  with  device  drivers  through  a  set  of  subfunctions  grouped  under  Interrupt 
21H  Function  44H  (lOCTL).  See  SYSTEM  CALLS:  Interrupt  21h:  Function  44H.  The 
lOCTL  subfunctions  that  are  particularly  applicable  to  the  character  I/O  needs  of  appli¬ 
cation  programs  are 


Subfunction  Name 

OOH  Get  Device  Data 

OlH  Set  Device  Data 

02H  Receive  Control  Data  from  Character  Device 


(more) 
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Subfiinction  Name 

03H  Send  Control  Data  to  Character  Device 

06H  Check  Input  Status 

07H  Check  Output  Status 

OAH  Check  if  Handle  is  Remote  (version  3. 1  or  later) 

OCH  Generic  I/O  Control  for  Handles:  Get/Set  Output  Iteration  Count 

Various  bits  in  the  device  information  word  returned  by  Subfunction  OOH  can  be  tested 
by  an  application  to  determine  whether  a  specific  handle  is  associated  with  a  character 
device  or  a  file  and  whether  the  driver  for  the  device  can  process  control  strings  passed  by 
Subfunctions  02H  and  03H.  The  device  information  word  also  allows  the  program  to  test 
whether  a  character  device  is  the  CLOCK$,  standard  input,  standard  output,  or  NUL  device 
and  whether  the  device  is  in  raw  or  cooked  mode.  The  program  can  then  use  Subfunction 
OlH  to  select  raw  mode  or  cooked  mode  for  subsequent  I/O  performed  with  the  handle. 

Subfunctions  02H  and  03H  allow  control  strings  to  be  passed  between  the  device  driver 
and  an  application;  they  do  not  usually  result  in  any  physical  I/O  to  the  device.  For  exam¬ 
ple,  a  custom  device  driver  might  allow  an  application  program  to  configure  the  serial  port 
by  writing  a  specific  set  of  control  parameters  to  the  driver  with  Subfunction  03H.  Simi¬ 
larly,  the  custom  driver  might  respond  to  Subfunction  02H  by  passing  the  application  a 
series  of  bytes  that  defines  the  current  configuration  and  status  of  the  serial  port. 

Subfunctions  06H  and  07H  can  be  used  by  application  programs  to  test  whether  a  device  is 
ready  to  accept  an  output  character  or  has  a  character  ready  for  input.  These  subfunctions 
are  particularly  applicable  to  the  serial  communications  ports  and  parallel  printer  ports 
because  MS-DOS  does  not  supply  traditional  function  calls  to  test  their  status. 

Subfunction  OAH  can  be  used  to  determine  whether  the  character  device  associated 
with  a  handle  is  local  or  remote — that  is,  attached  to  the  computer  the  program  is  running 
on  or  attached  to  another  computer  on  a  local  area  network.  A  program  should  not  or¬ 
dinarily  attempt  to  distinguish  between  local  and  remote  devices  during  normal  input  and 
output,  but  the  information  can  be  useful  in  attempts  to  recover  from  error  conditions. 

This  subfunction  is  available  only  if  Microsoft  Networks  is  running. 

Finally,  Subfunction  OCH  allows  a  program  to  query  or  set  the  number  of  times  a  device 
driver  tries  to  send  output  to  the  printer  before  assuming  the  device  is  not  available. 

lOCTL  programming  examples 

Example:  Use  lOCTL  Subfunction  OOH  to  obtain  the  device  information  word  for  the  stan¬ 
dard  input  handle  and  save  it,  and  then  use  Subfunction  OlH  to  place  standard  input  into 
raw  mode. 

info  dw  ?  ;  save  device  information  word  here 


(more) 
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mov  ax,4400h 

mov  bx,0 

int  21h 

mov  info,dx 

or  dl,20h 

mov  dh ,  0 

mov  ax, 4401 h 

int  21 h 


AH  =  function  44H,  lOCTL 

AL  =  subfunction  OOH,  get  device 

information  word 

BX  =  handle  for  standard  input 

transfer  to  MS-DOS 

save  device  information  word 

(assumes  DS  =  data  segment) 

set  raw  mode  bit 

and  clear  DH  as  MS-DOS  requires 

AL  =  subfunction  01 H,  set  device 

information  word 

(BX  still  contains  handle) 

transfer  to  MS-DOS 


Example:  Use  lOCTL  Subfunction  06H  to  test  whether  a  character  is  ready  for  input  on  the 
first  serial  port.  The  function  returns  AL  =  OFFH  if  a  character  is  ready  and  AL  =  OOH  if  not. 


mov 

ax, 4406H 

;  AH  =  function  44H,  lOCTL 
;  AL  =  subfunction  06H,  get 
;  input  status 

mov 

bx,3 

;  BX  =  handle  for  standard  aux 

int 

21h 

;  transfer  to  MS-DOS 

or 

al,  al 

;  test  status  of  AUX  driver 

jnz 

ready 

;  jump  if  input  character  ready 
;  else  no  character  is  waiting 

Jim  Kyle 
Chip  Rabinowitz 
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Article  6 

Interrupt-Diiven  Communications 


In  the  earliest  days  of  personal-computer  communications,  when  speeds  were  no  faster 
than  300  bits  per  second,  primitive  programs  that  moved  characters  to  and  from  the 
remote  system  were  adequate.  The  PC  had  time  between  characters  to  determine  what  it 
ought  to  do  next  and  could  spend  that  time  keeping  track  of  the  status  of  the  remote 
system. 

Modern  data-transfer  rates,  however,  are  four  to  eight  times  faster  and  leave  little  or  no 
time  to  spare  between  characters.  At  1200  bits  per  second,  as  many  as  three  characters  can 
be  lost  in  the  time  required  to  scroll  the  display  up  one  line.  At  such  speeds,  a  technique  to 
permit  characters  to  be  received  and  simultaneously  displayed  becomes  necessary. 

Mainframe  systems  have  long  made  use  of  hardware  interrupts  to  coordinate  such 
activities.  The  processor  goes  about  its  normal  activity;  when  a  peripheral  device  needs 
attention,  it  sends  an  interrupt  request  to  the  processor.  The  processor  interrupts  its  activ¬ 
ity,  services  the  request,  and  then  goes  back  to  what  it  was  doing.  Because  the  response  is 
driven  by  the  request,  this  type  of  processing  is  known  as  interrupt-driven.  It  gives  the 
effect  of  doing  two  things  at  the  same  time  without  requiring  two  separate  processors. 

Successful  telecommunication  with  PCs  at  modern  data  rates  demands  an  interrupt-driven 
routine  for  data  reception.  This  article  discusses  in  detail  the  techniques  for  interrupt- 
driven  communications  and  culminates  in  two  sample  program  packages. 

The  article  begins  by  establishing  the  purpose  of  communications  programs  and  then 
discusses  the  capability  of  the  simple  functions  provided  by  MS-DOS  to  achieve  this  goal. 
To  see  what  must  be  done  to  supplement  MS-DOS  functions,  the  hardware  (both  the 
modem  and  the  serial  port)  is  examined.  This  leads  to  a  discussion  of  the  method  MS-DOS 
has  provided  since  version  2.0  for  solving  the  problems  of  special  hardware  interfacing: 
the  installable  device  driver. 

With  the  background  established,  alternate  paths  to  interrupt-driven  communications  are 
discussed — one  following  recommended  MS-DOS  techniques,  the  other  following  stan¬ 
dard  industry  practice — and  programs  are  developed  for  each. 

Throughout  this  article,  the  discussion  is  restricted  to  the  architecture  and  BIOS  of  the  IBM 
PC  family.  MS-DOS  systems  not  totally  compatible  with  this  architecture  may  require  sub¬ 
stantially  different  approaches  at  the  detailed  level,  but  the  same  general  principles  apply. 


Purpose  of  Communications  Programs 

The  primary  purpose  of  any  communications  program  is  communicating — that  is,  trans¬ 
mitting  information  entered  as  keystrokes  (or  bytes  read  from  a  file)  in  a  form  suitable  for 
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transmission  to  a  remote  computer  via  phone  lines  and,  conversely,  converting  informa¬ 
tion  received  from  the  remote  computer  into  a  display  on  the  video  screen  (or  data  in  a 
file). 

Some  years  ago,  the  most  abstract  form  of  all  communications  programs  was  dubbed  a 
modem  engine,  by  analogy  to  Babbage’s  analytical  engine  or  the  inference-engine  model 
used  in  artificial-intelligence  development.  The  functions  of  the  modem  engine  are  com¬ 
mon  to  all  kinds  of  communications  programs,  from  the  simplest  to  the  most  complex, 
and  can  be  described  in  a  type  of  pseudo-C  as  follows: 

The  Modem  Engine  Pseudocode 

DO  {  IF  (input  character  is  available) 
send_it_to_remote; 

IF  (remote  character  is  available) 
use_it_locally; 

}  UNTIL  (told_to_stop) ; 

The  essence  of  this  modem-engine  code  is  that  the  absence  of  an  input  character,  or  of  a 
character  from  the  remote  computer,  does  not  hang  the  loop  in  a  wait  state.  Rather,  the 
engine  continues  to  cycle:  If  it  finds  work  to  do,  it  does  it;  if  not,  the  engine  keeps  looking. 

Of  course,  at  times  it  is  desirable  to  halt  the  continuous  action  of  the  modem  engine.  For 
example,  when  receiving  a  long  message,  it  is  nice  to  be  able  to  pause  and  read  the  mes¬ 
sage  before  the  lines  scroll  into  oblivion.  On  the  other  hand,  taking  too  long  to  study  the 
screen  means  that  incoming  characters  are  lost.  The  answer  is  a  technique  called  flow  con¬ 
trol,  in  which  a  special  control  character  is  sent  to  shut  down  transmission  and  some  other 
character  is  later  sent  to  start  it  up  again. 

Several  conventions  for  flow  control  exist.  One  of  the  most  widespread  is  known  as 
XON/XOFF,  from  the  old  Teletype-33  keycap  legends  for  the  two  control  codes  involved. 

In  the  original  use,  XOFF  halted  the  paper  tape  reader  and  XON  started  it  going  again.  In 
mid-1967,  the  General  Electric  Company  began  using  these  signals  in  its  time-sharing  com¬ 
puter  services  to  control  the  flow  of  data,  and  the  practice  rapidly  spread  throughout  the 
industry. 

The  sample  program  named  ENGINE,  shown  later  in  this  article,  is  an  almost  literal  imple¬ 
mentation  of  the  modem-engine  approach.  This  sample  represents  one  extreme  of  sim¬ 
plicity  in  communications  programs.  The  other  sample  program,  CTERM.C,  is  much  more 
complex,  but  the  modem  engine  is  still  at  its  heart. 


Using  Simple  MS-DOS  Functions 

Because  MS-DOS  provides,  among  its  standard  service  functions,  the  capability  of  sending 
output  to  or  reading  input  from  the  device  named  AUX  (which  defaults  to  COMl,  the  first 
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serial  port  on  most  machines),  a  first  attempt  at  implementing  the  modem  engine  using 
MS-DOS  functions  might  look  something  like  the  following  incomplete  fragment  of 
Microsoft  Macro  Assembler  (MASM)  code: 

/Incomplete  (and  Unworkable)  Implementation 


LOOP :  MOV 

AH, 08h 

/  read  keyboard,  no  echo 

INT 

21h 

MOV 

DL,AL 

/  set  up  to  send 

MOV 

AH, 04h 

/  send  to  AUX  device 

INT 

21h 

MOV 

AH,03h 

/  read  from  AUX  device 

INT 

21h 

MOV 

DL,AL 

/  set  up  to  send 

MOV 

AH, 02h 

/  send  to  screen 

INT 

21h 

JMP 

LOOP 

/  keep  doing  it 

The  problem  with  this  code  is  that  it  violates  the  keep-looking  principle  both  at  the  key¬ 
board  and  at  the  AUX  port:  Interrupt  21H  Function  OSH  does  not  return  until  a  keyboard 
character  is  available,  so  no  data  from  the  AUX  port  can  be  read  until  a  key  is  pressed 
locally.  Similarly,  Function  03H  waits  for  a  character  to  become  available  from  AUX,  so  no 
more  keys  can  be  recognized  locally  until  the  remote  system  sends  a  character.  If  nothing 
is  received,  the  loop  waits  forever. 

To  overcome  the  problem  at  the  keyboard  end.  Function  OBH  can  be  used  to  determine  if 
a  key  has  been  pressed  before  an  attempt  is  made  to  read  one,  as  shown  in  the  following 
modification  of  the  fragment: 

/Improved,  (but  Still  Unworkable)  Implementation 


LOOP: 

MOV 

AH, OBh 

/  test  keyboard  for  char 

INT 

21h 

OR 

AL,AL 

/  test  for  zero 

JZ 

RMT 

/  no  char  avail,  skip 

MOV 

AH, 08h 

/  have  char,  read  it  in 

INT 

21h 

MOV 

DL,AL 

/  set  up  to  send 

MOV 

AH,04h 

/  send  to  AUX  device 

INT 

21h 

RMT: 

MOV 

AH, 03h 

/  read  from  AUX  device 

INT 

21h 

MOV 

DL,AL 

/  set  up  to  send 

MOV 

AH, 02h 

/  send  to  screen 

INT 

21h 

JMP 

LOOP 

/  keep  doing  it 

This  code  permits  any  input  from  AUX  to  be  received  without  waiting  for  a  local  key  to 
be  pressed,  but  if  AUX  is  slow  about  providing  input,  the  program  waits  indefinitely  before 
checking  the  keyboard  again.  Thus,  the  problem  is  only  partially  solved. 
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MS-DOS,  however,  simply  does  not  provide  any  direct  method  of  making  the  required 
tests  for  AUX  or,  for  that  matter,  any  of  the  serial  port  devices.  That  is  why  communications 
programs  must  be  treated  differently  from  most  other  types  of  programs  under  MS-DOS 
and  why  such  programs  must  be  intimately  involved  with  machine  details  despite  all 
accepted  principles  of  portable  program  design. 


The  Hardware  Involved 

Personal-computer  communications  require  at  least  two  distinct  pieces  of  hardware  (sepa¬ 
rate  devices,  even  though  they  are  often  combined  on  a  single  board).  These  hardware 
items  are  the  serial  port,  which  converts  data  from  the  computer’s  internal  bus  into  a  bit 
stream  for  transmission  over  a  single  external  line,  and  the  modem,  which  converts  the  bit 
stream  into  a  form  suitable  for  telephone-line  (or,  sometimes,  radio)  transmission. 

The  modem 

The  modem  (a  word  coined  from  MOdulator-DEModulator)  is  a  device  that  converts  a 
stream  of  bits,  represented  as  sequential  changes  of  voltage  level,  into  audio  frequency  sig¬ 
nals  suitable  for  transmission  over  voice-grade  telephone  circuits  (modulation)  and  con¬ 
verts  these  signals  back  into  a  stream  of  bits  that  duplicates  the  original  input  (demodu¬ 
lation). 

Specific  characteristics  of  the  audio  signals  involved  were  established  by  AT&T  when  that 
company  monopolized  the  modem  industry,  and  those  characteristics  then  evolved  into 
de  facto  standards  when  the  monopoly  vanished.  They  take  several  forms,  depending  on 
the  data  rate  in  use;  these  forms  are  normally  identified  by  the  original  Bell  specification 
number,  such  as  103  (for  600  bps  and  below)  or  212A  (for  the  1200  bps  standard). 

The  data  rate  is  measured  in  bits  per  second  (bps),  often  mistermed  baud  or  even  “baud 
per  second.”  A  baud  measures  the  number  of  signals  per  second;  as  with  knot  (nautical 
miles  per  hour),  the  time  reference  is  built  in.  If  one  signal  change  marks  one  bit,  as  is  true 
for  the  Bell  103  standard,  then  baud  and  bps  have  equal  values.  However,  they  are  not 
equivalent  for  more  complex  signals.  For  example,  the  Bell  212A  diphase  standard  for  1200 
bps  uses  two  tone  streams,  each  operating  at  600  baud,  to  transmit  data  at  1200  bits  per 
second. 

For  accuracy,  this  article  uses  bps,  rather  than  baud,  except  where  widespread  industry 
misuse  of  baud  has  become  standardized  (as  in  “baud  rate  generator”). 

Originally,  the  modem  itself  was  a  box  connected  to  the  computer’s  serial  port  via  a  cable. 
Characteristics  of  this  cable,  its  connectors,  and  its  signals  were  standardized  in  the  1960s 
by  the  Electronic  Industries  Association  (EIA),  in  Standard  RS232C.  Like  the  Bell  standards 
for  modems,  RS232C  has  survived  almost  unchanged.  Its  characteristics  are  listed  in 
Table  6-1. 
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Table  6-1.  R$232C  Signals. 


DB25Pin 

232 

Name 

Description 

1 

Safety  Ground 

2 

BA 

TXD 

Transmit  Data 

3 

BB 

RXD 

Receive  Data 

4 

CA 

RTS 

Request  To  Send 

5 

CB 

CTS 

Clear  To  Send 

6 

CC 

DSR 

Data  Set  Ready 

7 

AB 

GND 

Signal  Ground 

8 

CF 

DCD 

Data  Carrier  Detected 

20 

CD 

DTR 

Data  Terminal  Ready 

22 

CE 

RI 

Ring  Indicator 

With  the  increasing  popularity  of  personal  computers,  internal  modems  that  plug  into  the 
PC’s  motherboard  and  combine  the  modem  and  a  serial  port  became  available. 

The  first  such  units  were  manufactured  by  Hayes  Corporation,  and  like  Bell  and  the  EIA, 
they  created  a  standard.  Functionally,  the  internal  modem  is  identical  to  the  combination 
of  a  serial  port,  a  connecting  cable,  and  an  external  modem. 

The  serial  port 

Each  serial  port  of  a  standard  IBM  PC  connects  the  rest  of  the  system  to  a  type  INS8250 
Universal  Asynchronous  Receiver  Transmitter  (UART)  integrated  circuit  (IC)  chip  devel¬ 
oped  by  National  Semiconductor  Corporation.  This  chip,  along  with  associated  circuits  in 
the  port, 

1 .  Converts  data  supplied  via  the  system  data  bus  into  a  sequence  of  voltage  levels  on 
the  single  TXD  output  line  that  represent  binary  digits. 

2.  Converts  data  received  as  a  sequence  of  binary  levels  on  the  single  RXD  input  line 
into  bytes  for  the  data  bus. 

3.  Controls  the  modem’s  actions  through  the  DTR  and  RTS  output  lines. 

4.  Provides  status  information  to  the  processor;  this  information  comes  from  the 
modem,  via  the  DSR,  DCD,  CTS,  and  RI  input  lines,  and  from  within  the  UART  itself, 
which  signals  data  available,  data  needed,  or  error  detected. 

The  word  asynchronoiAS  in  the  name  of  the  IC  comes  from  the  Bell  specifications.  When 
computer  data  is  transmitted,  each  bit’s  relationship  to  its  neighbors  must  be  preserved; 
this  can  be  done  in  either  of  two  ways.  The  most  obvious  method  is  to  keep  the  bit  stream 
strictly  synchronized  with  a  clock  signal  of  known  frequency  and  count  the  cycles  to  iden¬ 
tify  the  bits.  Such  a  transmission  is  known  as  synchronous,  often  abbreviated  to  synch  or 
sometimes  bisync  for  binary  synchronous.  The  second  method,  first  used  with  mechanical 
teleprinters,  marks  the  start  of  each  bit  group  with  a  defined  start  bit  and  the  end  with  one 
or  more  defined  stop  bits,  and  it  defines  a  duration  for  each  bit  time.  Detection  of  a  start  bit 
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marks  the  beginning  of  a  received  group;  the  signal  is  then  sampled  at  each  bit  time  until 
the  stop  bit  is  encountered.  This  method  is  known  as  asynchronous  (or  just  asynch)  and  is 
the  one  used  by  the  standard  IBM  PC. 

The  start  bit  is,  by  definition,  exactly  the  same  as  that  used  to  indicate  binary  zero,  and  the 
stop  bit  is  the  same  as  that  indicating  binary  one.  A  zero  signal  is  often  called  SPACE,  and  a 
one  signal  is  called  MARK,  from  terms  used  in  the  teleprinter  industry. 

During  transmission,  the  least  significant  bit  of  the  data  is  sent  first,  after  the  start  bit.  A 
parity  bit,  if  used,  appears  as  the  most  significant  bit  in  the  data  group,  before  the  stop  bit 
or  bits;  it  cannot  be  distinguished  from  a  databit  except  by  its  position.  Once  the  first  stop 
bit  is  sent,  the  line  remains  in  MARK  (sometimes  called  idling)  condition  until  a  new  start 
bit  indicates  the  beginning  of  another  group. 

In  most  PC  uses,  the  serial  port  transfers  one  8-bit  byte  at  a  time,  and  the  term  word  speci¬ 
fies  a  l6-bit  quantity.  In  the  UART  world,  however,  a  word  is  the  unit  of  information  sent  by 
the  chip  in  each  chunk.  The  word  length  is  part  of  the  control  information  set  into  the  chip 
during  setup  operations  and  can  be  5, 6, 7,  or  8  bits.  This  discussion  follows  UART  conven¬ 
tions  and  refers  to  words,  rather  than  to  bytes. 

One  special  type  of  signal,  not  often  used  in  PC-to-PC  communications  but  sometimes 
necessary  in  communicating  with  mainframe  systems,  is  a  BREAK.  The  BREAK  is  an  all- 
SPACE  condition  that  extends  for  more  than  one  word  time,  including  the  stop-bit  time. 
(Many  systems  require  the  BREAK  to  last  at  least  150  milliseconds  regardless  of  data  rate.) 
Because  it  cannot  be  generated  by  any  normal  data  character  transmission,  the  BREAK  is 
used  to  interrupt,  or  break  into,  normal  operation.  The  IBM  PC’s  8250  UART  can  generate 
the  BREAK  signal,  but  its  duration  must  be  determined  by  a  program,  rather  than  by  the 
chip. 

The  8250  UART  architecture 

The  8250  UART  contains  four  major  functional  areas:  receiver,  transmitter,  control  circuits, 
and  status  circuits.  Because  these  areas  are  closely  related,  some  terms  used  in  the  follow¬ 
ing  descriptions  are,  of  necessity,  forward  references  to  subsequent  paragraphs. 

The  major  parts  of  the  receiver  are  a  shift  register  and  a  data  register  called  the  Received 
Data  Register.  The  shift  register  assembles  sequentially  received  data  into  word-parallel 
form  by  shifting  the  level  of  the  RXD  line  into  its  front  end  at  each  bit  time  and,  at  the  same 
time,  shifting  previous  bits  over.  When  the  shift  register  is  full,  all  bits  in  it  are  moved  over 
to  the  data  register,  the  shift  register  is  cleared  to  all  zeros,  and  the  bit  in  the  status  circuits 
that  indicates  data  ready  is  set.  If  an  error  is  detected  during  receipt  of  that  word,  other  bits 
in  the  status  circuits  are  also  set. 

Similarly,  the  major  parts  of  the  transmitter  are  a  holding  register  called  the  Transmit 
Holding  Register  and  a  shift  register.  Each  word  to  be  transmitted  is  transferred  from  the 
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data  bus  to  the  holding  register.  If  the  holding  register  is  not  empty  when  this  is  done,  the 
previous  contents  are  lost.  The  transmitter's  shift  register  converts  word-parallel  data  into 
bit-serial  form  for  transmission  by  shifting  the  most  significant  bit  out  to  the  TXD  line  once 
each  bit  time,  at  the  same  time  shifting  lower  bits  over  and  shifting  in  an  idling  bit  at  the 
low  end  of  the  register.  When  the  last  databit  has  been  shifted  out,  any  data  in  the  holding 
register  is  moved  to  the  shift  register,  the  holding  register  is  filled  with  idling  bits  in  case 
no  more  data  is  forthcoming,  and  the  bit  in  the  status  circuits  that  indicates  the  Transmit 
Holding  Register  is  empty  is  set  to  indicate  that  another  word  can  be  transferred.  The 
parity  bit,  if  any,  and  stop  bits  are  added  to  the  transmitted  stream  after  the  last  databit 
of  each  word  is  shifted  out. 

The  control  circuits  establish  three  communications  features:  first,  line  control  values, 
such  as  word  length,  whether  or  not  (and  how)  parity  is  checked,  and  the  number  of  stop 
bits;  second,  modem  control  values,  such  as  the  state  of  the  DTR  and  RTS  output  lines;  and 
third,  the  rate  at  which  data  is  sent  and  received.  These  control  values  are  established  by 
two  8-bit  registers  and  one  l6-bit  register,  which  are  addressed  as  four  8-bit  registers.  They 
are  the  Line  Control  Register  (LCR),  the  Modem  Control  Register  (MCR),  and  the  l6-bit 
BRG  Divisor  Latch,  addressed  as  BaudO  and  Baudl. 

The  BRG  Divisor  Latch  sets  the  data  rate  by  defining  the  bit  time  produced  by  the  Pro¬ 
grammable  Baud  Rate  Generator  (PBRG),  a  major  part  of  the  control  circuits.  The  PBRG 
can  provide  any  data  speed  from  a  few  bits  per  second  to  38400  bps;  in  the  BIOS  of  the 
IBM  PC,  PC/XT,  and  PC/AT,  though,  only  the  range  110  through  9600  bps  is  supported. 

How  the  LCR  and  the  MCR  establish  their  control  values,  how  the  PBRG  is  programmed, 
and  how  interrupts  are  enabled  are  discussed  later. 

The  fourth  major  area  in  the  8250  UART,  the  status  circuits,  records  (in  a  pair  of  status 
registers)  the  conditions  in  the  receive  and  transmit  circuits,  any  errors  that  are  detected, 
and  any  change  in  state  of  the  RS232C  input  lines  from  the  modem.  When  any  status  regis¬ 
ter’s  content  changes,  an  interrupt  request,  if  enabled,  is  generated  to  notify  the  rest  of  the 
PC  system.  This  approach  lets  the  PC  attend  to  other  matters  without  having  to  continually 
monitor  the  status  of  the  serial  port,  yet  it  assures  immediate  action  when  something  does 
occur. 

The  8250  programming  interface 

Not  all  the  registers  mentioned  in  the  preceding  section  are  accessible  to  programmers. 
The  shift  registers,  for  example,  can  be  read  from  or  written  to  only  by  the  8250’s  internal 
circuits.  There  are  10  registers  available  to  the  programmer,  and  they  are  accessed  by  only 
seven  distinct  addresses  (shown  in  Table  6-2).  The  Received  Data  Register  and  the 
Transmit  Holding  Register  share  a  single  address  (a  read  gets  the  received  data;  a  write 
goes  to  the  holding  register).  In  addition,  both  this  address  and  that  of  the  Interrupt  Enable 
Register  (lER)  are  shared  with  the  PBRG  Divisor  Latch.  A  bit  in  the  Line  Control  Register 
called  the  Divisor  Latch  Access  Bit  (DLAB)  determines  which  register  is  addressed  at  any 
specific  time. 


Section  II:  Programming  in  the  MS-DOS  Environment  173 


Part  B:  Programming  for  MS-DOS 


In  the  IBM  PC,  the  seven  addresses  used  by  the  8250  are  selected  by  the  low  3  bits  of  the 
port  number  (the  higher  bits  select  the  specific  port).  Thus,  each  serial  port  occupies  eight 
positions  in  the  address  space.  However,  only  the  lowest  address  used — the  one  in  which 
the  low  3  bits  are  all  0 — need  be  remembered  in  order  to  access  all  eight  addresses. 

Because  of  this,  any  serial  port  in  the  PC  is  referred  to  by  an  address  that,  in  hexadecimal 
notation,  ends  with  either  0  or  8:  The  COMl  port  normally  uses  address  03F8H,  and  COM2 
uses  02F8H.  This  lowest  port  address  is  usually  called  the  base  port  address,  and  each 
addressable  register  is  then  referenced  as  an  offset  from  this  base  value,  as  shown  in 
Table  6-2. 

Table  6-2.  8250  Port  Offsets  from  Base  Address. 


Offset  Name  Description 

IfDLAB  bit  inLCR  =  0: 

OOH  DATA 


OlH  lER 

IfDLAB  bit  inLCR  =  l: 

OOH  BaudO 

OlH  Baudl 

Not  affected  by  DLAB  bit: 

02H  IID 

03H  LCR 

04H  MCR 

05H  LSR 

06H  MSR 

The  control  circuits 

The  control  circuits  of  the  8250  include  the  Programmable  Baud  Rate  Generator  (PBRG), 
the  Line  Control  Register  (LCR),  the  Modem  Control  Register  (MCR),  and  the  Interrupt  En¬ 
able  Register  (lER). 

The  PBRG  establishes  the  bit  time  used  for  both  transmitting  and  receiving  data  by  divid¬ 
ing  an  external  clock  signal.  To  select  a  desired  bit  rate,  the  appropriate  divisor  is  loaded 
into  the  PBRG’s  l6-bit  Divisor  Latch  by  setting  the  Divisor  Latch  Access  Bit  (DLAB)  in  the 
Line  Control  Register  to  1  (which  changes  the  functions  of  addresses  0  and  1)  and  then 
writing  the  divisor  into  BaudO  and  Baudl.  After  the  bit  rate  is  selected,  DLAB  is  changed 
back  to  0,  to  permit  normal  operation  of  the  DATA  registers  and  the  lER. 


Received  Data  Register  if 
read  from.  Transmit  Holding 
Register  if  written  to 
Interrupt  Enable  Register 


BRG  Divisor  Latch,  low  byte 
BRG  Divisor  Latch,  high  byte 


Interrupt  Identifier  Register 
Line  Control  Register 
Modem  Control  Register 
Line  Status  Register 
Modem  Status  Register 
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With  the  1.8432  MHz  external  UART  clock  frequency  used  in  standard  IBM  systems, 
divisor  values  (in  decimal  notation)  for  bit  rates  between  45.5  and  38400  bps  are  listed  in 
Table  6-3.  These  speeds  are  established  by  a  crystal  contained  in  the  serial  port  (or  internal 
modem)  and  are  totally  unrelated  to  the  speed  of  the  processor’s  clock. 

Table  6-3.  Bit  Rate  Divisor  Table  for  8250/IBM. 


BPS 

Divisor 

45.5 

2532 

50 

2304 

75 

1536 

110 

1047 

134.5 

857 

150 

768 

300 

384 

600 

192 

1200 

96 

1800 

64 

2000 

58 

2400 

48 

4800 

24 

9600 

12 

19200 

6 

38400 

3 

The  remaining  control  circuits  are  the  Line  Control  Register,  the  Modem  Control  Register, 
and  the  Interrupt  Enable  Register.  Bits  in  the  LCR  control  the  assignment  of  offsets  0  and  1, 
transmission  of  the  BREAK  signal,  parity  generation,  the  number  of  stop  bits,  and  the  word 
length  sent  and  received,  as  shown  in  Table  6-4. 

Table  6-4.  8250  Line  Control  Register  Bit  Values. 


Bit 

Name 

Binary 

Meaning 

Address  Control: 

7 

DLAB 

Oxxxxxxx 

Ixxxxxxx 

Offset  0  refers  to  DATA; 

offset  1  refers  to  lER 
Offsets  0  and  1  refer  to 
BRG  Divisor  Latch 

BREAK  Control: 

6 

SETBRK 

xOxxxxxx 

xlxxxxxx 

Normal  UART  operation 
Send  BREAK  signal 

(more) 
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Table  6-4.  Continued. 


Bit 

Name 

Binary 

Meaning 

Parity  Checking: 
5,4,3 

GENPAR 

xxxxOxxx 

No  parity  bit 

xxOOlxxx 

Parity  bit  is  ODD 

xxOllxxx 

Parity  bit  is  EVEN 

xxlOlxxx 

Parity  bit  is  1 

xxlllxxx 

Parity  bit  is  0 

Stop  Bits: 

2 

XSTOP 

xxxxxOxx 

Only  1  stop  bit 

xxxxxlxx 

2  stop  bits 

(1.5ifWL=5) 

Word  Length: 

1,0 

WD5 

xxxxxxOO 

Word  length  =  5 

WD6 

xxxxxxOl 

Word  length  =  6 

WD7 

xxxxxxlO 

Word  length  =  7 

WD8 

xxxxxxll 

Word  length  =  8 

Two  bits  in  the  MCR  (Table  6-5)  control  output  lines  DTR  and  RTS;  two  other  MCR  bits 
(OUTl  and  OUT2)  are  left  free  by  the  UART  to  be  assigned  by  the  user;  a  fifth  bit  (TEST) 
puts  the  UART  into  a  self-test  mode  of  operation.  The  upper  3  bits  have  no  effect  on  the 
UART  The  MCR  can  be  both  read  from  and  written  to. 

Both  of  the  user-assignable  bits  are  defined  in  the  IBM  PC.  OUTl  is  used  by  Hayes  internal 
modems  to  cause  a  power-on  reset  of  their  circuits;  OUT2  controls  the  passage  of  UART- 
generated  interrupt  request  signals  to  the  rest  of  the  PC.  Unless  OUT2  is  set  to  1,  interrupt 
signals  from  the  UART  cannot  reach  the  rest  of  the  PC,  even  though  all  other  controls  are 
properly  set.  This  feature  is  documented,  but  obscurely,  in  the  IBM  Technical  Reference 
manuals  and  the  asynchronous-adapter  schematic;  it  is  easy  to  overlook  when  writing  an 
interrupt-driven  program  for  these  machines. 


Table  6-5.  8250  Modem  Control  Register  Bit  Values. 


Name 

Binary 

Description 

TEST 

xxxlxxxx 

Turns  on  UART  self-test  configuration. 

OUT2 

xxxxlxxx 

Controls  8250  interrupt  signals  (User2  Output). 

OUTl 

xxxxxlxx 

Resets  Hayes  1200b  internal  modem  (Userl  Output). 

RTS 

xxxxxxlx 

Sets  RTS  output  to  RS232C  connector. 

DTR 

xxxxxxxl 

Sets  DTR  output  to  RS232C  connector. 
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The  8250  can  generate  any  or  all  of  four  classes  of  interrupts,  each  individually  enabled  or 
disabled  by  setting  the  appropriate  control  bit  in  the  Interrupt  Enable  Register  (Table  6-6). 
Thus,  setting  the  lER  to  OOH  disables  all  the  UART  interrupts  within  the  8250  without 
regard  to  any  other  settings,  such  as  OUT2,  system  interrupt  masking,  or  the  CLI/STI  com¬ 
mands.  The  lER  can  be  both  read  from  and  written  to.  Only  the  low  4  bits  have  any  effect 
on  the  UART. 

Table  6-6.  8250  Interrupt  Enable  Register  Constants. 

Binary  Action 

xxxxlxxx  Enable  Modem  Status  Interrupt, 

xxxxxlxx  Enable  Line  Status  Interrupt, 

xxxxxxlx  Enable  Transmit  Register  Interrupt, 

xxxxxxxl  Enable  Received  Data  Ready  Interrupt. 

The  status  circuits 

The  status  circuits  of  the  8250  include  the  Line  Status  Register  (LSR),  the  Modem  Status 
Register  (MSR),  the  Interrupt  Identifier  (IID)  Register,  and  the  interrupt-request  generation 
system. 

The  8250  includes  circuitry  that  detects  a  received  BREAK  signal  and  also  detects  three 
classes  of  data-reception  errors.  Separate  bits  in  the  LSR  (Table  6-7)  are  set  to  indicate  that 
a  BREAK  has  been  received  and  to  indicate  any  of  the  following:  a  parity  error  (if  lateral 
parity  is  in  use),  a  framing  error  (incoming  bit  =  0  at  stop-bit  time),  or  an  overrun  error 
(word  not  yet  read  from  receive  buffer  by  the  time  the  next  word  must  be  moved  into  it). 

The  remaining  bits  of  the  LSR  indicate  the  status  of  the  Transmit  Shift  Register,  the 
Transmit  Holding  Register,  and  the  Received  Data  Register;  the  most  significant  bit  of  the 
LSR  is  not  used  and  is  always  0.  The  LSR  is  a  read-only  register;  writing  to  it  has  no  effect. 

Table  6-7.  8250  Line  Status  Register  Bit  Values. 

Bit  Binary  Meaning 

7  Oxxxxxxx  Always  zero 

6  xlxxxxxx  Transmit  Shift  Register  empty 

5  xxlxxxxx  Transmit  Holding  Register  empty 

4  xxxlxxxx  BREAK  received 

3  xxxxlxxx  Framing  error 

2  xxxxxlxx  Parity  error 

1  xxxxxxlx  Overrun  error 

0  xxxxxxxl  Received  data  ready 
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The  MSR  (Table  6-8)  monitors  the  four  RS232C  lines  that  report  modem  status.  The  upper 
4  bits  of  this  register  indicate  the  voltage  level  of  the  associated  RS232C  line;  the  lower  4 
bits  indicate  that  the  voltage  level  has  changed  since  the  register  was  last  read. 


Table  6-8.  8250  Modem  Status  Register  Bit  Values. 


Bit 

Binary 

Meaning 

7 

Ixxxxxxx 

Data  Carrier  Detected  (DCD)  level 

6 

xlxxxxxx 

Ring  Indicator  (RI)  level 

5 

xxlxxxxx 

Data  Set  Ready  (DSR)  level 

4 

xxxlxxxx 

Clear  To  Send  (CTS)  level 

3 

xxxxlxxx 

DCD  change 

2 

xxxxxlxx 

RI  change 

1 

xxxxxxlx 

DSR  change 

0 

xxxxxxxl 

CTS  change 

As  mentioned  previously,  four  types  of  interrupts  are  generated.  The  four  types  are  iden¬ 
tified  by  flag  values  in  the  IID  Register  (Table  6-9).  These  flags  are  set  as  follows: 

•  Change  of  any  bit  value  in  the  MSR  sets  the  modem  status  flag. 

•  Setting  of  the  BREAK  Received  bit  or  any  of  the  three  error  bits  in  the  LSR  sets  the  line 
status  flag. 

•  Setting  of  the  Transmit  Holding  Register  Empty  bit  in  the  LSR  sets  the  transmit  flag. 

•  Setting  of  the  Received  Data  Ready  bit  in  the  LSR  sets  the  receive  flag. 

The  IID  register  indicates  the  interrupt  type,  even  though  the  lER  may  be  disabling  that 
type  of  interrupt  from  generating  any  request.  The  IID  is  a  read-only  register;  attempts  to 
write  to  it  have  no  effect. 

Table  6-9.  8250  Interrupt  Identification  and  Causes. 


nD  content  Meaning 


xxxxxxxlB 

xxxxxOOOB 

xxxxxOlOB 

xxxxxlOOB 

xxxxxllOB 


No  interrupt  active 

Modem  Status  Interrupt;  bit  changed  in  MSR 
Transmit  Register  Interrupt;  Transmit  Holding  Register  empty,  bit 
set  in  LSR 

Received  Data  Ready  Interrupt;  Data  Register  full,  bit  set  in  LSR 
Line  Status  Interrupt;  BREAK  or  error  bit  set  in  LSR 


As  shown  in  Table  6-9,  an  all-zero  value  (which  in  most  of  the  other  registers  is  a  totally 
disabling  condition)  means  that  a  Modem  Status  Interrupt  condition  has  not  yet  been  ser¬ 
viced.  A  modem  need  not  be  connected,  however,  for  a  Modem  Status  Interrupt  condition 
to  occur;  all  that  is  required  is  for  one  of  the  RS232C  non-data  input  lines  to  change  state, 
thus  changing  the  MSR. 
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Whenever  a  flag  is  set  in  the  IID,  the  UART  interrupt-request  generator  will,  if  enabled 
by  the  UART  programming,  generate  an  interrupt  request  to  the  processor.  Two  or  more 
interrupts  can  be  active  at  the  same  time;  if  so,  more  than  one  flag  in  the  IID  register  is  set. 

The  IID  flag  for  each  interrupt  type  (and  the  LSR  or  MSR  bits  associated  with  it)  clears 
when  the  corresponding  register  is  read  (or,  in  one  case,  written  to).  For  example,  reading 
the  content  of  the  MSR  clears  the  modem  status  flag;  writing  a  byte  to  the  DATA  register 
clears  the  transmit  flag;  reading  the  DATA  register  clears  the  receive  flag;  reading  the  LSR 
clears  the  line  status  flag.  The  LSR  or  MSR  bit  does  not  clear  until  it  has  been  read;  the  IID 
flag  clears  with  the  LSR  or  MSR  bit. 

Programming  the  UART 

Each  time  power  is  applied,  any  serial-interface  device  must  be  programmed  before  it  is 
used.  This  programming  can  be  done  by  the  computer’s  bootstrap  sequence  or  as  a  part  of 
the  port  initialization  routines  performed  when  a  port  driver  is  installed.  Often,  both  tech¬ 
niques  are  used:  The  bootstrap  provides  default  conditions,  and  these  can  be  modified 
during  initialization  to  meet  the  needs  of  each  port  driver  used  in  a  session. 

When  the  8250  chip  is  programmed,  the  BRG  Divisor  Latch  should  be  set  for  the  proper 
baud  rate,  the  LCR  and  MGR  should  be  loaded,  the  lER  should  be  set,  and  all  internal  inter¬ 
rupt  requests  and  the  receive  buffer  should  be  cleared.  The  sequence  in  which  these  are 
done  is  not  especially  critical,  but  any  pending  interrupt  requests  should  be  cleared  before 
they  are  permitted  to  pass  on  to  the  rest  of  the  PC. 

The  following  sample  code  performs  these  startup  actions,  setting  up  the  chip  in  device 
COMl  (at  port  03F8H)  to  operate  at  1200  bps  with  a  word  length  of  8  bits,  no  parity  check¬ 
ing,  and  all  UART  interrupts  enabled.  (In  practical  code,  all  values  for  addresses  and 
operating  conditions  would  not  be  built  in;  these  values  are  included  in  the  example  to 
clarify  what  is  being  done  at  each  step.) 


MOV 

DX, 03FBh 

;  base  port  COMl  (03F8)  +  ] 

MOV 

AL, 080h 

;  enable 

Divisor  Latch 

OUT 

DX,AL 

MOV 

DX, 03F8h 

;  set  for  BaudO 

MOV 

AX,  96 

;  set  divisor  to  1200  bps 

OUT 

DX,AL 

INC 

DX 

;  to  offset  1  for  Baudi 

MOV 

AL,AH 

;  high  byte  of  divisor 

OUT 

DX,AL 

MOV 

DX, 03FBh 

;  back  to  the  LCR  offset 

MOV 

AL,  03 

;  DLAB  = 

0,  Parity  =  N,  WL 

OUT 

DX,AL 

MOV 

DX, 03F9h 

;  offset 

1  for  lER 

MOV 

AL, OFh 

;  enable 

all  ints  in  8250 

OUT 

DX,  AL 

MOV 

DX, 03FCh 

;  COMl  + 

MCR  (4) 

MOV 

AL, OBh 

;  OUT2  + 

RTS  +  DTR  bits 

OUT 

DX,AL 

(more) 
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CLRGS : 


MOV 

DX,03FDh 

IN 

AL,DX 

MOV 

DX,03F8h 

IN 

AL,DX 

MOV 

DX, 03FEh 

IN 

AL,DX 

MOV 

DX, 03FAh 

IN 

AL,DX 

IN 

AL,DX 

TEST 

AL,  1 

JZ 

CLRGS 

clear  LSR 
clear  RX  reg 
clear  MSR 
I ID  reg 

repeat  to  be  sure 
int  pending? 
yes,  repeat 


Note:  This  code  does  not  completely  set  up  the  IBM  serial  port.  Although  it  fully  programs 
the  8250  itself,  additional  work  remains  to  be  done.  The  system  interrupt  vectors  must  be 
changed  to  provide  linkage  to  the  interrupt  service  routine  (ISR)  code,  and  the  8259 
Priority  Interrupt  Controller  (PIC)  chip  must  also  be  programmed  to  respond  to  interrupt 
requests  from  the  UART  channels.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRON¬ 
MENT:  Customizing  ms-dos:  Hardware  Interrupt  Handlers. 


Device  Drivers 

All  versions  of  MS-DOS  since  2.0  have  permitted  the  installation  of  user-provided  device 
drivers.  From  the  standpoint  of  operating-system  theory,  using  such  drivers  is  the  proper 
way  to  handle  generic  communications  interfacing.  The  following  paragraphs  are  intended 
as  a  refresher  and  to  explain  this  article’s  departure  from  standard  device-driver  terminol¬ 
ogy.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Customizing  ms-dos: 
Installable  Device  Drivers. 

An  installable  device  driver  consists  of  (1)  a  driver  header  that  links  the  driver  to 
others  in  the  chain  maintained  by  MS-DOS,  tells  the  system  the  characteristics  of  this  spe¬ 
cific  driver,  provides  pointers  to  the  two  major  routines  contained  in  the  driver,  and  (for  a 
character-device  driver)  identifies  the  driver  by  name;  (2)  any  data  and  storage  space  the 
driver  may  require;  and  (3)  the  two  major  code  routines. 

The  code  routines  are  called  the  Strategy  routine  and  the  Interrupt  routine  in  normal 
device-driver  descriptions.  Neither  has  any  connection  with  the  hardware  interrupts  dealt 
with  by  the  drivers  presented  in  this  article.  Because  of  this,  the  term  Request  routine  is 
used  instead  of  Interrupt  routine,  so  that  hardware  interrupt  code  can  be  called  an 
interrupt  service  routine  (ISR)  with  minimal  chances  for  confusion. 

MS-DOS  communicates  with  a  device  driver  by  reserving  space  for  a  command  packet 
of  as  many  as  22  bytes  and  by  passing  this  packet’s  address  to  the  driver  with  a  call  to  the 
Strategy  routine.  All  data  transfer  between  MS-DOS  and  the  driver,  in  both  directions, 
occurs  via  this  command  packet  and  the  Request  routine.  The  operating  system  places  a 
command  code  and,  optionally,  a  byte  count  and  a  buffer  address  into  the  packet  at  the 
specified  locations,  then  calls  the  Request  routine.  The  driver  performs  the  command 
and  returns  the  status  (and  sometimes  a  byte  count)  in  the  packet. 
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Two  Alternative  Approaches 

Now  that  the  factors  involved  in  creating  interrupt-driven  communications  programs  have 
been  discussed,  they  can  be  put  together  into  practical  program  packages.  Etoing  so  brings 
out  not  only  general  principles  but  also  minor  details  that  make  the  difference  between 
success  and  failure  of  program  design  in  this  hardware-dependent  and  time-critical  area. 

The  traditional  way:  Going  it  alone 

Because  MS-DOS  provides  no  generic  functions  suitable  for  communications  use,  virtually 
all  popular  communications  programs  provide  and  install  their  own  port  driver  code,  and 
then  remove  it  before  returning  to  MS-DOS.  This  approach  entails  the  creation  of  a  com¬ 
munications  handler  for  each  program  and  requires  the  ^‘uninstallation”  of  the  handler  on 
exit  from  the  program  that  uses  it.  Despite  the  extra  requirements,  most  communications 
programs  use  this  method. 

The  alternative:  Creating  a  communications  device  driver 

Instead  of  providing  temporary  interface  code  that  must  be  removed  from  the  system 
before  returning  to  the  command  level,  an  installable  device  driver  can  be  built  as  a 
replacement  for  COMx  so  that  every  program  can  have  all  features.  However,  this 
approach  is  not  compatible  with  existing  terminal  programs  because  it  has  never  been  a 
part  of  MS-DOS. 

Comparison  of  the  two  methods 

The  traditional  approach  has  several  advantages,  the  most  obvious  being  that  the  driver 
code  can  be  fully  tailored  to  the  needs  of  the  program.  Because  only  one  program  will 
ever  use  the  driver,  no  general  cases  need  be  considered. 

However,  if  a  user  wants  to  keep  communications  capability  available  in  a  terminate-and- 
stay-resident  (TSR)  module  for  background  use  and  also  wants  a  different  type  of  commu¬ 
nications  program  running  in  the  foreground  (not,  of  course,  while  the  background  task  is 
using  the  port),  the  background  program  and  the  foreground  job  must  each  have  its  own 
separate  driver  code.  And,  because  such  code  usually  includes  buffer  areas,  the  duplicated 
drivers  represent  wasted  resources. 

A  single  communications  device  driver  that  is  installed  when  the  system  powers  up  and 
that  remains  active  until  shutdown  avoids  wasting  resources  by  allowing  both  the  back¬ 
ground  and  foreground  tasks  to  share  the  driver  code.  Until  such  drivers  are  common, 
however,  it  is  unlikely  that  commercial  software  will  be  able  to  make  use  of  them.  In  addi¬ 
tion,  such  a  driver  must  either  provide  totally  general  capabilities  or  it  must  include  control 
interfaces  so  each  user  program  can  dynamically  alter  the  driver  to  suit  its  needs. 

At  this  time,  the  use  of  a  single  driver  is  an  interesting  exercise  rather  than  a  practical 
application,  although  a  possible  exception  is  a  dedicated  system  in  which  all  software  is 
either  custom  designed  or  specially  modified.  In  such  a  system,  the  generalized  driver 
can  provide  significant  improvement  in  the  efficiency  of  resource  allocation. 
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A  Device-Driver  Program  Package 


Despite  the  limitations  mentioned  in  the  preceding  section,  the  first  of  the  two  complete 
packages  in  this  article  uses  the  concept  of  a  separate  device  driver.  The  driver  handles  all 
hardware-dependent  interfacing  and  thus  permits  extreme  simplicity  in  all  other  modules 
of  the  package.  This  approach  is  presented  first  because  it  is  especially  well  suited  for  in¬ 
troducing  the  concepts  of  communications  programs.  However,  the  package  is  not  merely 
a  tutorial  device:  It  includes  some  features  that  are  not  available  in  most  commercial 
programs. 

The  package  itself  consists  of  three  separate  programs.  First  is  the  device  driver,  which 
becomes  a  part  of  MS-DOS  via  the  CONFIG.SYS  file.  Second  is  the  modem  engine,  which 
is  the  actual  terminal  program.  (A  functionally  similar  component  forms  the  heart  of  every 
communications  program,  whether  it  is  written  in  assembly  language  or  a  high-level  lan¬ 
guage  and  regardless  of  the  machine  or  operating  system  in  use.)  Third  is  a  separately  exe¬ 
cuted  support  program  that  permits  changing  such  driver  characteristics  as  word  length, 
parity,  and  baud  rate. 

In  most  programs  that  use  the  traditional  approach,  the  driver  and  the  support  program 
are  combined  with  the  modem  engine  in  a  single  unit  and  the  resulting  mass  of  detail 
obscures  the  essential  simplicity  of  each  part.  Here,  the  parts  are  presented  as  separate 
modules  to  emphasize  that  simplicity. 

The  device  driver:  COMDVR. ASM 

The  device  driver  is  written  to  augment  the  default  COMl  and  COM2  devices  with  other 
devices  named  ASYl  and  ASY2  that  use  the  same  physical  hardware  but  are  logically  sepa¬ 
rate.  The  driver  (COMDVR. ASM)  is  implemented  in  MASM  and  is  shown  in  the  listing  in 
Figure  6-1.  Although  the  driver  is  written  basically  as  a  skeleton,  it  is  designed  to  permit 
extensive  expansion  and  can  be  used  as  a  general-purpose  sample  of  device-driver 
source  code. 

The  code 

1  :  Title 

2  :  ; 

3  :  ; 

4  :  ; 

5  :  ; 

6  :  ; 

7  :  ; 

8  :  Subttl 

9  : 

10  : 

1 1  :  Dbg 

12  : 

13  : 


COMDVR  Driver  for  IBM  COM  Ports 
Jim  Kyle,  1987 

Based  on  ideas  from  many  sources . 

including  Mike  Higgins,  CLM  March  1985; 
public-domain  INTBIOS  program  from  BBS's; 
COMBIOS.COM  from  CIS  Programmers'  SIG;  and 
ADVANCED  MS-DOS  by  Ray  Duncan. 

MS-DOS  Driver  Definitions 

Comment  *  This  comments  out  the  Dbg  macro . 

Macro  Ltrl , Ltr2, Ltr3  ;  used  only  to  debug  driver... 
Local  Xxx 

Push  Es  ;  save  all  regs  used 


Figure  6-1.  COMDVR. ASM. 


(more) 


182  The  MS-DOS  Encyclopedia 


Article  6:  Interrupt-Driven  Communications 


14 

Push 

Di 

15 

Push 

Ax 

16 

Les 

Di,Cs 

Dbgptr  ;  get  pointer  to  CRT 

17 

Mov 

Ax, Es : 

[di] 

18 

Mov 

Al,Ltr1 

;  move  in  letters 

19 

Stosw 

20 

Mov 

Al,Ltr2 

21 

Stosw 

22 

Mov 

Al,Ltr3 

23 

Stosw 

24 

Cmp 

Di, 1 600 

;  top  10  lines  only 

25 

Jb 

Xxx 

26 

Xor 

Di,  Di 

27 

Xxx: 

Mov 

Word  Ptr 

Cs : Dbgptr, Di 

28 

Pop 

Ax 

29 

Pop 

Di 

30 

Pop 

Es 

31 

Endm 

32 

* 

;  asterisk  ends  commented-out 

region 

33 

; 

34 

9 

Device  Type  Codes 

35 

DevChr 

Equ 

8000h 

; 

this  is  a  character  device 

36 

DevBlk 

Equ 

OOOOh 

; 

this  is  a  block  (disk)  device 

37 

Devloc 

Equ 

4000h 

r 

this  device  accepts  lOCTL  requests 

38 

DevNon 

Equ 

2000h 

; 

non-IBM  disk  driver  (block  only) 

39 

DevOTB 

Equ 

2000h 

i 

MS-DOS  3.x  out  until  busy  supported 

(char) 

40 

DevOCR 

Equ 

0800h 

; 

MS-DOS  3.x  open/close/rm  supported 

41 

DevX32 

Equ 

0040h 

/ 

MS-DOS  3.2  functions  supported 

42 

DevSpc 

Equ 

OOlOh 

/ 

accepts  special  interrupt  29H 

43 

DevClk 

Equ 

0008h 

; 

this  is  the  CLOCK  device 

44 

DevNul 

Equ 

0004h 

r 

this  is  the  NUL  device 

45 

DevSto 

Equ 

0002h 

; 

this  is  standard  output 

46 

DevSti 

Equ 

OOOIh 

; 

this  is  standard  input 

47 

; 

48 

; 

Error 

Status  BITS 

49 

StsErr 

Equ 

8000h 

; 

general  error 

50 

StsBsy 

Equ 

0200h 

; 

device  busy 

51 

StsDne 

Equ 

OlOOh 

; 

request  completed 

52 

; 

53 

; 

•  Error 

Reason  values  for  lower-order  bits 

54 

ErrWp 

Equ 

0 

write  protect  error 

55 

ErrUu 

Equ 

1 

unknown  unit 

56 

ErrDnr 

Equ 

2 

drive  not  ready 

57 

ErrUc 

Equ 

3 

unknown  command 

58 

ErrCrc 

Equ 

4 

cyclical  redundancy  check  error 

59 

ErrBsl 

Equ 

5 

bad  drive  request  structure  length 

60 

ErrSl 

Equ 

6 

seek  error 

61 

ErrUm 

Equ 

7 

unknown  media 

62 

ErrSnf 

Equ 

8 

sector  not  found 

63 

ErrPop 

Equ 

9 

printer  out  of  paper 

64 

ErrWf 

Equ 

10 

write  fault 
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65 

ErrRf 

Equ 

11 

read  fault 

66 

ErrGf 

Equ 

12 

general  failure 

67 

; 

68 

; 

Structure  of  an  I/O  request  packet  header. 

69 

; 

70 

Pack 

Struc 

71 

Len 

Db 

? 

length  of  record 

72 

Prtno 

Db 

? 

unit  code 

73 

Code 

Db 

? 

command  code 

74 

Stat 

Dw 

o 

return  status 

75 

Dosq 

Dd 

7 

(unused  MS-DOS  queue  link  pointer) 

76 

Devq 

Dd 

7 

(unused  driver  queue  link  pointer) 

77 

Media 

Db 

7 

media  code  on  read/write 

78 

Xfer 

Dw 

7 

xfer  address  offset 

79 

Xseg 

Dw 

7 

xfer  address  segment 

80 

Count 

Dw 

7 

transfer  byte  count 

81 

Sector 

Dw 

7 

starting  sector  value  (block  only) 

82 

Pack 

Ends 

83 

84 

Subttl 

IBM-PC 

Hardware  Driver  Definitions 

85 

page 

86 

; 

87 

; 

8259  data 

88 

PIC_b 

Equ 

020h 

port  for  EOI 

89 

PIC_e 

Equ 

021h 

port  for  Int  enabling 

90 

EOI 

Equ 

020h 

EOI  control  word 

91 

; 

92 

; 

8250  port  offsets 

93 

RxBuf 

Equ 

0F8h 

base  address 

94 

Baudi 

Equ 

RxBuf+1 

baud  divisor  high  byte 

95 

IntEn 

Equ 

RxBuf+1 

interrupt  enable  register 

96 

Intid 

Equ 

RxBuf+2 

interrupt  identification  register 

97 

Lctrl 

Equ 

RxBuf+3 

line  control  register 

98 

Mctr-1 

Equ 

RxBuf+4 

modem  control  register 

99 

Lstat 

Equ 

RxBuf+5 

line  status  register 

100 

Mstat 

Equ 

RxBuf+6 

modem  status  register 

101 

/ 

102 

/ 

8250  LCR 

constants 

103 

Dlab 

Equ 

10000000b  ;  divisor  latch  access  bit 

104 

SetBrk 

Equ 

01000000b  ;  send  break  control  bit 

105 

StkPar 

Equ 

00100000b  ;  stick  parity  control  bit 

106 

EvnPar 

Equ 

00010000b  ;  even  parity  bit 

107 

GenPar 

Equ 

00001000b  ;  generate  parity  bit 

108 

Xstop 

Equ 

00000100b  ;  extra  stop  bit 

109 

Wd8 

Equ 

00000011b  ;  word  length  =  8 

110 

Wd7 

Equ 

00000010b  ;  word  length  =  7 

111 

Wd6 

Equ 

00000001b  ;  word  length  =  6 

112 

; 

113 

; 

8250  LSR 

constants 

114 

xsre 

Equ 

01000000b  ;  xmt  SR  empty 

115 

xhre 

Equ 

00100000b  ;  xmt  HR  empty 
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116 

BrkRcv 

Equ 

00010000b 

;  break  received 

117 

FrmErr 

Equ 

00001000b 

;  framing  error 

118 

ParErr 

Equ 

00000100b 

;  parity  error 

119 

OveRun 

Equ 

00000010b 

;  overrun  error 

120 

rdta 

Equ 

00000001b 

;  received  data  ready 

121 

AnyErr 

Equ 

BrkRcv+FrmErr+ParErr+OveRun 

122 

; 

123 

; 

8250  MCR  constants 

124 

LpBk 

Equ 

00010000b 

;  UART  out  loops  to  in  (test) 

125 

Usr2 

Equ 

00001000b 

;  Gates  8250  interrupts 

126 

Usrl 

Equ 

00000100b 

;  aux  userl  output 

127 

SetRTS 

Equ 

00000010b 

;  sets  RTS  output 

128 

SetDTR 

Equ 

00000001b 

;  sets  DTR  output 

129 

; 

130 

; 

8250  MSR  constants 

131 

CDlvl 

Equ 

10000000b 

;  carrier  detect  level 

132 

RIlvl 

Equ 

01000000b 

;  ring  indicator  level 

133 

DSRlvl 

Equ 

00100000b 

;  DSR  level 

134 

CTSlvl 

Equ 

00010000b 

;  CTS  level 

135 

CDchg 

Equ 

00001000b 

;  Carrier  Detect  change 

136 

RIchg 

Equ 

00000100b 

;  Ring  Indicator  change 

137 

DSRchg 

Equ 

00000010b 

;  DSR  change 

138 

CTSchg 

Equ 

00000001b 

;  CTS  change 

139 

; 

140 

; 

8250  lER  constants 

141 

S_Int 

Equ 

00001000b 

;  enable  status  interrupt 

142 

E_Int 

Equ 

00000100b 

;  enable  error  interrupt 

143 

X_Int 

Equ 

00000010b 

;  enable  transmit  interrupt 

144 

R_Int 

Equ 

00000001b 

;  enable  receive  interrupt 

145 

Allint 

Equ 

00001111b 

;  enable  all  interrupts 

146 

147 

Subttl 

Definitions  for  THIS  Driver 

148 

page 

149 

150 

/ 

Bit  definitions  for  the  output  status 

byte 

151 

/ 

(  this  driver  only  ) 

152 

Linidl 

Equ 

Offh 

if  all  bits  off,  xmitter  is 

idle 

153 

LinXof 

Equ 

1 

output  is  suspended  by  XOFF 

154 

LinDSR 

Equ 

2 

output  is  suspended  until  DSR  comes  on 

155 

LinCTS 

Equ 

4 

output  is  suspended  until  CTS  comes  on 

156 

/ 

157 

Bit  definitions  for  the  input  status  byte 

158 

( 

this  driver  only  ) 

159 

Badinp 

Equ 

1 

input  line  errors  have  been 

detected 

160 

LostDt 

Equ 

2 

receiver  buffer  overflowed. 

data  lost 

161 

OffLin 

Equ 

4 

device  is  off  line  now 

162 

163 

164 

165 

166 


Bit  definitions  for  the  special  characteristics  words 
{  this  driver  only  ) 

InSpec  controls  how  input  from  the  UART  is  treated 
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167 

168 

InEpc 

Equ 

OOOlh 

;  errors  translate  to  codes  with  parity  bit  on 

169 

170 

• 

OutSpec 

controls  how  output  to  the  UART  is  treated 

171 

OutDSR 

Equ 

OOOlh 

;  DSR  is  used  to  throttle  output  data 

172 

OutCTS 

Equ 

0002h 

;  CTS  is  used  to  throttle  output  data 

173 

OutXon 

Equ 

0004h 

;  XON/XOFF  is  used  to  throttle  output  data 

174 

OutCdf 

Equ 

OOlOh 

;  carrier  detect  is  off-line  signal 

175 

176 

OutDrf 

Equ 

0020h 

;  DSR  is  off-line  signal 

177 

Unit 

Struc 

;  each  unit  has  a  structure  defining  its  state: 

178 

Port 

Dw 

7 

;  I/O  port  address 

179 

Vect 

Dw 

7 

;  interrupt  vector  offset  (NOT  interrupt  number! 

180 

Isradr 

Dw 

7 

;  offset  to  interrupt  service  routine 

181 

182 

OtStat 

Db 

Wd8 

;  default  LCR  bit  settings  during  INIT, 

;  output  status  bits  after 

183 

184 

InStat 

Db 

Usr2+SetRTS+SetDTR  ;  MCR  bit  settings  during  INIT, 

;  input  status  bits  after 

185 

InSpec 

Dw 

InEpc 

;  special  mode  bits  for  INPUT 

186 

OutSpec 

Dw 

OutXon 

;  special  mode  bits  for  OUTPUT 

187 

Baud 

Dw 

96 

;  current  baud  rate  divisor  value  (1200  b) 

188 

Ifirst 

Dw 

0 

;  offset  of  first  character  in  input  buffer 

189 

lavail 

Dw 

0 

;  offset  of  next  available  byte 

190 

Ibuf 

Dw 

7 

;  pointer  to  input  buffer 

191 

Ofirst 

Dw 

0 

;  offset  of  first  character  in  output  buffer 

192 

Oavail 

Dw 

0 

;  offset  of  next  avail  byte  in  output  buffer 

193 

194 

Obuf 

Unit 

Dw 

Ends 

7 

;  pointer  to  output  buffer 

195 

196 

197 

198 

199 

200 
201 
202 

203 

204 

205 

206 

207 

208 

209 

210 
21 1 
212 

213 

214 

215 

216 
217 


Driver 


Beginning  of  driver  code  and  data 
Segment 

Assume  Cs: driver,  ds: driver,  es: driver 


Async2 : 


Org 

Dw 

Dw 

Dw 

Dw 

Db 

Dw 

Dw 

Dw 

Dw 

Db 


Async2, -1 
DevChr  +  Devloc 
Strtegy 
Request  1 
'ASY1  ' 

-n-1 

DevChr  +  Devloc 
Strtegy 
Request2 
'ASY2  ' 


drivers  start  at  0 

pointer  to  next  device 
character  device  with  lOCTL 
offset  of  Strategy  routine 
offset  of  interrupt  entry  point  1 
device  1  name 

pointer  to  next  device:  MS-DOS  fills  in 
character  device  with  lOCTL 
offset  of  Strategy  routine 
offset  of  interrupt  entry  point  2 
device  2  name 


;dbgptr  Dd  ObOOOOOOOh 

;  Following  is  the  storage  area  for  the  request  packet  pointer 

Figure  6-1.  Continued. 
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218 

; 

219 

PackHd 

Dd 

0 

220 

; 

221 

; 

baud  rate  conversion 

table 

222 

Asy_baudt  Dw 

50, 

2304 

;  first  value  is  desired  baud  rate 

223 

Dw 

75, 

1536 

;  second  is  divisor  register  value 

224 

Dw 

110, 

1047 

225 

Dw 

134, 

857 

226 

Dw 

150, 

786 

227 

Dw 

300, 

384 

228 

Dw 

600, 

192 

229 

Dw 

1200, 

96 

230 

Dw 

1800, 

64 

231 

Dw 

2000, 

58 

232 

Dw 

2400, 

48 

233 

Dw 

3600, 

32 

234 

Dw 

4800, 

24 

235 

Dw 

7200, 

16 

236 

Dw 

9600, 

12 

237 

238 

;  table 

of  structures 

239 

; 

ASY1 

defaults  to  the  COM1  port,  INT  OCH  vector,  XON, 

240 

; 

no  parity,  8  databits. 

1  stop 

bit,  and  1200  baud 

241 

Asy_tab1 

242 

Unit 

<3f 8h, 30h, asy1 isr, , , , 

, , , , ini buf, , , outi buf > 

243 

244 

; 

ASY2 

defaults  to  the  COM2  port,  INT  OBH  vector,  XON, 

245 

; 

no  parity,  8  databits. 

1  stop 

bit,  and  1200  baud 

246 

Asy_tab2 : 

247 

Unit 

<2f 8h, 2ch, asy2isr, , , , 

, , , , in2buf , , , out2buf> 

248 

249 

Bufsiz 

Equ 

256 

;  input  buffer  size 

250 

Bufmsk 

= 

Bufsiz-1 

;  mask  for 

calculating  offsets  modulo  bufsiz 

251 

Ini buf 

Db 

Bufsiz  DUP 

(?) 

252 

Outi buf 

Db 

Bufsiz  DUP 

(?) 

253 

In2buf 

Db 

Bufsiz  DUP 

(?) 

254 

Out2buf 

Db 

Bufsiz  DUP 

(?) 

255 

; 

256 

; 

Following 

is  a 

table 

of  offsets  to  all  the  driver  functions 

2bl 

258 

Asy_funcs: 

259 

Dw 

Init 

;  0 

initialize  driver 

260 

Dw 

Mchek 

;  1 

media  check  (block  only) 

261 

Dw 

BldBPB 

;  2 

build  BPB  (block  only) 

262 

Dw 

loctlin 

;  3 

lOCTL  read 

263 

Dw 

Read 

;  4 

read 

264 

Dw 

Ndread 

;  5 

nondestructive  read 

265 

Dw 

Rxstat 

;  6 

input  status 

266 

Dw 

Inflush 

;  7 

flush  input  buffer 

267 

Dw 

Write 

;  8 

write 

268 

Dw 

Write 

;  9 

write  with  verify 
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269 

Dw 

Txstat 

;  10  output  status 

270 

Dw 

Txf lush 

;  1 1  flush  output  buffer 

271 

Dw 

loctlout 

;  12  lOCTL  write 

272 

;  Following  are 

not  used 

in  this  driver . 

273 

Dw 

Zexit 

;  13  open  (3.x  only,  not  used) 

274 

Dw 

Zexit 

;  14  close  (3.x  only,  not  used) 

275 

Dw 

Zexit 

;  15  rem  med  (3.x  only,  not  used) 

276 

Dw 

Zexit 

;  16  out  until  bsy  (3.x  only,  not  used) 

277 

Dw 

Zexit 

;  17 

278 

Dw 

Zexit 

;  18 

279 

Dw 

Zexit 

;  19  generic  lOCTL  request  (3.2 

only) 

280 

Dw 

Zexit 

;  20 

281 

Dw 

Zexit 

;  21 

282 

Dw 

Zexit 

;  22 

283 

Dw 

Zexit 

;  23  get  logical  drive  map  (3.2 

only) 

284 

Dw 

Zexit 

;  24  set  logical  drive  map  (3.2 

only) 

285 

286 

Subttl  Driver 

Code 

287 

Page 

288 

; 

289 

;  The  Strategy  routine  itself: 

290 

; 

291 

Strtegy  Proc 

Far 

292 

;  dbg 

'S' , 'R' , 

• 

293 

Mov 

Word  Ptr 

CS:PackHd,BX  ;  store  the  offset 

294 

MOV 

Word  Ptr 

CS:PackHd+2, ES  ;  store  the  segment 

295 

Ret 

296 

Strtegy  Endp 

297 

; 

298 

Request 1 : 

;  asynci  has  been  requested 

299 

Push 

Si 

;  save  SI 

300 

Lea 

Si,Asy_tab1  ;  get  the  device  unit  table  address 

301 

Jmp 

Short  Gen_request 

302 

303 

Request2 : 

;  async2  has  been  requested 

304 

Push 

Si 

;  save  SI 

305 

Lea 

Si,Asy_tab2  ;  get  unit  table  two's  address 

306 

307 

Gen_request : 

308 

;  dbg 

'R', 'R', 

I 

309 

Pushf 

;  save  all  regs 

310 

Cld 

311 

Push 

Ax 

312 

Push 

Bx 

313 

Push 

Cx 

314 

Push 

Dx 

315 

Push 

Di 

316 

Push 

Bp 

317 

Push 

Ds 

318 

Push 

Es 

31  9 

Push 

Cs 

;  set  DS  =  CS 

Figure  6-1.  Continued.  (more) 
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320 

Pop 

Ds 

321 

Les 

Bx,PackHd  ; 

get  packet  pointer 

322 

Lea 

Di,Asy_funcs  ; 

point  DI  to  jump  table 

323 

Mov 

Al, es : code [bx]  ; 

command  code 

324 

Cbw 

325 

Add 

Ax , Ax  ; 

double  to  word 

326 

Add 

Di,  ax 

327 

Jmp 

[di] 

go  do  it 

328 

; 

329 

; 

Exit 

from  driver  request 

330 

; 

331 

ExitP 

Proc 

Far 

332 

Bsyexit 

333 

Mov 

Ax, StsBsy 

334 

Jmp 

Short  Exit 

335 

336 

Mchek : 

337 

BldBPB: 

338 

Zexit : 

Xor 

Ax,  Ax 

339 

Exit: 

Les 

Bx,PackHd  ; 

get  packet  pointer 

340 

Or 

Ax, StsDne 

341 

Mov 

Es : Stat [Bx] , Ax  ; 

set  return  status 

342 

Pop 

Es 

restore  registers 

343 

Pop 

Ds 

344 

Pop 

Bp 

345 

Pop 

Di 

346 

Pop 

Dx 

347 

Pop 

Cx 

348 

Pop 

Bx 

349 

Pop 

Ax 

350 

Popf 

351 

Pop 

Si 

352 

Ret 

353 

ExitP 

Endp 

354 

355 

Subttl 

Driver  Service  Routines 

356 

Page 

357 

358 

; 

Read 

data  from  device 

359 

360 

Read: 

361 

; 

dbg 

•R','d',’  ' 

362 

Mov 

Cx, Es : Count [bx]  ; 

get  requested  nbr 

363 

Mov 

Di, Es : Xfer [bx]  ; 

get  target  pointer 

364 

Mov 

Dx, Es :Xseg [bx] 

365 

Push 

Bx 

save  for  count  fixup 

366 

Push 

Es 

367 

Mov 

Es,  Dx 

368 

Test 

InStat [si] , Badinp  Or  LostDt 

369 

Je 

No_lerr  ; 

no  error  so  far . . . 

370 

Add 

Sp,4 

error,  flush  SP 

Figure  6-1.  Continued. 
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371 

And 

InStat [si] , Not  { 

[  Badinp  Or  LostDt  ) 

372 

Mov 

Ax, ErrRf 

;  error,  report  it 

373 

Jmp 

Exit 

374 

No_lerr : 

375 

Call 

Get_in 

;  go  for  one 

376 

Or 

Ah,  Ah 

377 

Jnz 

Got _ all 

;  none  to  get  now 

378 

Stosb 

;  store  it 

379 

Loop 

No_lerr 

;  go  for  more 

380 

Got_all : 

381 

Pop 

Es 

382 

Pop 

Bx 

383 

Sub 

Di, Es :Xfer [bx] 

;  calc  number  stored 

384 

Mov 

Es : Count [bx] , Di 

;  return  as  count 

385 

Jmp 

Zexit 

386 

387 

;  ;  Nondestructive  read  from  device 

388 

389 

Ndread: 

390 

Mov 

Di, ifirst [si] 

391 

Cmp 

Di, iavail [si] 

392 

Jne 

Ndget 

393 

Jmp 

Bsyexit 

;  buffer  empty 

394 

Ndget : 

395 

Push 

Bx 

396 

Mov 

Bx, ibuf [si] 

397 

Mov 

Al, [bx+di] 

398 

Pop 

Bx 

399 

Mov 

Es :media [bx] , al 

;  return  char 

400 

Jmp 

Zexit 

401 

402 

;  Input 

status  request 

403 

404 

Rxstat : 

405 

Mov 

Di, ifirst [si] 

406 

Cmp 

Di, iavail [si] 

407 

Jne 

Rxful 

408 

Jmp 

Bsyexit 

;  buffer  empty 

409 

Rxf ul : 

410 

Jmp 

Zexit 

;  have  data 

41 1 

412 

;  Input 

flush  request 

413 

414 

Inflush: 

415 

Mov 

Ax, iavail [si] 

416 

Mov 

Ifirst [si] , ax 

417 

Jmp 

Zexit 

418 

41  9 

;  Output 

data  to  device 

420 

Figure  6-1.  Continued. 
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421 

Write : 

422 

;  dbg 

423 

Mov 

Cx, es : count [bx] 

424 

Mov 

Di, es : xfer [bx] 

425 

Mov 

Ax,es:xseg[bx] 

426 

Mov 

Es,  ax 

427 

Wlup: 

428 

Mov 

Al, es : [di] 

; 

get  the  byte 

429 

Inc 

Di 

430 

Wwait : 

431 

Call 

Put_out 

; 

put  away 

432 

Cmp 

Ah,0 

433 

Jne 

Wwait 

; 

wait  for  room! 

434 

Call 

Start-output 

; 

get  it  going 

435 

Loop 

Wlup 

436 

437 

Jmp 

Zexit 

438 

439 

;  Output 

status  request 

440 

441 

Txstat : 

442 

Mov 

Ax, ofirst [si] 

443 

Dec 

Ax 

444 

And 

Ax,bufmsk 

445 

Cmp 

Ax, oavail [si] 

446 

Jne 

Txroom 

447 

Jmp 

Bsyexit 

/ 

buffer  full 

448 

Txroom: 

449 

Jmp 

Zexit 

; 

room  exists 

450 

451 

;  lOCTL 

read  request,  return  line  paramete 

452 

453 

loctlin: 

454 

Mov 

Cx, es : count [bx] 

455 

Mov 

Di, es :xfer [bx] 

456 

Mov 

Dx,es:xseg[bx] 

457 

Mov 

Es,  dx 

458 

Cmp 

Cx,  1  0 

.459 

Je 

Doiocin 

460 

Mov 

Ax, errbsl 

461 

Jmp 

Exit 

462 

Doiocin : 

463 

Mov 

Dx, port [si] 

; 

base  port 

464 

Mov 

DI, Lctrl 

; 

line  status 

465 

Mov 

Cx,4 

; 

LCR,  MCR,  LSR, 

466 

Getport : 

467 

In 

Al,  dx 

468 

Stos 

Byte  Ptr  [DI] 

469 

Inc 

Dx 

470 

Loop 

Getport 

471 

Figure  6-1.  Continued. 
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472 

Mov 

Ax, InSpec [si]  ; 

spec  in  flags 

473 

Stos 

Word  Ptr  [DI] 

474 

Mov 

Ax, Out Spec [si]  ; 

out  flags 

475 

Stos 

Word  Ptr  [DI] 

476 

Mov 

Ax, baud [si]  ; 

baud  rate 

477 

Mov 

Bx,  di 

478 

Mov 

Di, offset  Asy_baudt+2 

479 

Mov 

Cx,15 

480 

Baudcin 

481 

Cmp 

[di] , ax 

482 

Je 

Yesinb 

483 

Add 

Di,4 

484 

Loop 

Baudcin 

485 

Yesinb: 

486 

Mov 

Ax,  -2 [di] 

487 

Mov 

Di,  bx 

488 

Stos 

Word  Ptr  [DI] 

489 

Jmp 

Zexit 

490 

491 

i 

Flush 

output  buffer  request 

492 

493 

Txflush 

494 

Mov 

Ax, oavail [si] 

495 

Mov 

Of irst [si] , ax 

496 

Jmp 

Zexit 

497 

498 

; 

lOCTL 

request:  change  line  parameters  f( 

499 

500 

loctlout : 

501 

Mov 

Cx,es : count [bx] 

502 

Mov 

Di,es :xfer [bx] 

503 

Mov 

Dx,es:xseg[bx] 

504 

Mov 

Es,  dx 

505 

Cmp 

Cx,  10 

506 

Je 

Doiocout 

507 

Mov 

Ax, errbsl 

508 

Jmp 

Exit 

509 

510 

Doiocout : 

511 

Mov 

Dx, port [si]  ; 

base  port 

512 

Mov 

Dl,Lctrl 

line  Ctrl 

513 

Mov 

Al,  es : [di] 

514 

Inc 

Di 

515 

Or 

Al,Dlab 

set  baud 

516 

Out 

Dx,  al 

517 

Clc 

518 

Jnc 

$+2 

51  9 

Inc 

Dx 

mdm  Ctrl 

520 

Mov 

Al, es : [di] 

521 

Or 

Al,Usr2 

Int  Gate 

522 

Out 

Dx,  al 

Figure  6-1.  Continued. 
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523 

Add 

Di,3 

;  skip  LSR,MSR 

524 

Mov 

Ax,  es : [di] 

525 

Add 

Di,2 

526 

Mov 

InSpec [si] , ax 

527 

Mov 

Ax,  es :  [di] 

528 

Add 

Di,2 

529 

Mov 

OutSpec [si] , ax 

530 

Mov 

Ax,es: [di] 

;  set  baud 

531 

Mov 

Bx,  di 

532 

Mov 

Di, offset  Asy_baudt 

533 

Mov 

Cx,  15 

534 

:  Baudcout : 

535 

Cmp 

[di] , ax 

536 

Je 

Yesoutb 

537 

Add 

Di,4 

538 

Loop 

Baudcout 

539 

540 

Mov 

DI, Lctrl 

;  line  Ctrl 

541 

In 

Al,  dx 

;  get  LCR  data 

542 

And 

Al,not  Dlab 

;  strip 

543 

Clc 

544 

Jnc 

$+2 

545 

Out 

Dx,  al 

;  put  back 

546 

Mov 

Ax, ErrUm 

;  "unknown  media” 

547 

Jmp 

Exit 

548 

549 

Yesoutb; 

550 

Mov 

Ax, 2 [di] 

;  get  divisor 

551 

Mov 

Baud [si] , ax 

;  save  to  report  later 

552 

Mov 

Dx, port [si] 

;  set  divisor 

553 

Out 

Dx,  al 

554 

Clc 

555 

Jnc 

$+2 

556 

Inc 

Dx 

557 

Mov 

Al,  ah 

558 

Out 

Dx,  al 

559 

Clc 

560 

Jnc 

$+2 

561 

Mov 

DI, Lctrl 

;  line  Ctrl 

562 

In 

Al,  dx 

;  get  LCR  data 

563 

And 

Al,not  Dlab 

;  strip 

564 

Clc 

565 

Jnc 

$+2 

566 

Out 

Dx,  al 

;  put  back 

567 

Jmp 

Zexit 

568 

569 

Subttl 

Ring 

Buffer  Routines 

570 

Page 

571 

572 

Put_out 

Proc 

Near  ;  puts 

AL  into  output  ring  buffe; 

573  : 

Push 

Cx 

Figure  6-1.  Continued.  (more) 
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574 

Push 

Di 

575 

Pushf 

576 

Cli 

577 

Mov 

Cx, oavail [si] 

578 

Mov 

Di,  cx 

579 

Inc 

Cx 

580 

And 

Cx, bufmsk 

581 

Cmp 

Cx, ofirst [si] 

582 

Je 

Poerr 

583 

Add 

Di, obuf [si] 

584 

Mov 

[di],al 

585 

Mov 

Oavail [si] , cx 

586 

; 

dbg 

•p»,'o','  * 

587 

Mov 

> 

0 

588 

Jmp 

Short  Poret 

589 

Poerr : 

590 

Mov 

> 

1 

591 

Poret : 

592 

Popf 

593 

Pop 

Di 

594 

Pop 

Cx 

595 

Ret 

596 

Put_out 

Endp 

597 

598 

Get-out 

Proc 

Near  ;  gets 

599 

Push 

Cx 

600 

Push 

Di 

601 

Pushf 

602 

Cli 

603 

Mov 

Di, ofirst [si] 

604 

Cmp 

Di, oavail [si] 

605 

Jne 

Ngoerr 

606 

Mov 

Ah,-1 

607 

Jmp 

Short  Goret 

608 

Ngoerr : 

609 

; 

dbg 

'g' , '0* , '  ' 

610 

Mov 

Cx,  di 

611 

Add 

Di, obuf [si] 

612 

Mov 

Al,  [di] 

613 

Mov 

Ah,0 

614 

Inc 

Cx 

615 

And 

Cx, bufmsk 

616 

Mov 

Ofirst [si] , cx 

617 

Goret : 

618 

Popf 

619 

Pop 

Di 

620 

Pop 

Cx 

621 

Ret 

622 

Get_out 

Endp 

623 

624 

Put_in 

Proc 

Near  ;  puts 

Figure  6-1.  Continued. 


;  put  ptr 

;  bump 

;  overflow? 

;  yes,  don't 
;  no 

;  put  in  buffer 


next  character  from  output  ring  buffer 


;  get  ptr 
;  put  ptr 

;  empty 


;  get  char 

;  bump  ptr 
;  wrap 


the  char  from  AL  into  input  ring  buffer 
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625 

Push 

Cx 

626 

Push 

Di 

627 

Pushf 

628 

Cli 

629 

Mov 

Di, iavail [si] 

630 

Mov 

Cx,  di 

631 

Inc 

Cx 

632 

And 

Cx,bufmsk 

633 

Cmp 

Cx, ifirst [si] 

634 

Jne 

Npierr 

635 

Mov 

Ah,-1 

636 

Jmp 

Short  Piret 

637 

Npierr : 

638 

Add 

Di, ibuf [si] 

639 

Mov 

[di] ,al 

640 

Mov 

Iavail [si] ,  cx 

641 

; 

dbg 

•p', 'i', •  * 

642 

Mov 

Ah,0 

643 

Piret : 

644 

Popf 

645 

Pop 

Di 

646 

Pop 

Cx 

647 

Ret 

648 

Put_in 

Endp 

649 

650 

Get_in 

Proc 

Near  ;  gets 

651 

Push 

Cx 

652 

Push 

Di 

653 

Pushf 

654 

Cli 

655 

Mov 

Di, ifirst [si] 

656 

Cmp 

Di, iavail [si] 

657 

Je 

Gierr 

658 

Mov 

Cx,di 

659 

Add 

Di, ibuf [si] 

660 

Mov 

Al, [di] 

661 

Mov 

> 

o 

662 

; 

dbg 

'g’ , 'i* , '  ' 

663 

Inc 

Cx 

664 

And 

Cx, bufmsk 

665 

Mov 

Ifirst [si] , cx 

666 

Jmp 

Short  Giret 

667 

Gierr : 

668 

Mov 

Ah,-1 

669 

Giret : 

670 

Popf 

671 

Pop 

Di 

672 

Pop 

Cx 

673 

Ret 

674 

Get_in 

Endp 

675 

gets  one  from  input  ring  buffer  into  AL 


Figure  6-1.  Continued. 
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676 

Subttl 

Interrupt  Dispatcher  Routine 

677 

Page 

678 

679 

Asyl isr : 

680 

Sti 

681 

Push 

Si 

682 

Lea 

Si, asy_tab1 

683 

Jmp 

Short  Int_serve 

684 

685 

Asy2isr : 

686 

Sti 

687 

Push 

Si 

688 

Lea 

Si, asy_tab2 

689 

690 

:  Int_serve: 

691 

Push 

Ax  ;  save  all  regs 

692 

Push 

Bx 

693 

Push 

Cx 

694 

Push 

Dx 

695 

Push 

Di 

696 

Push 

Ds 

697 

Push 

Cs  ;  set  DS  =  CS 

698 

Pop 

Ds 

699 

:  Int_exit: 

700 

; 

dbg 

'I', 'x', *  ' 

701 

Mov 

Dx, Port [si]  ;  base  address 

702 

Mov 

Dl,lntld  ;  check  Int  ID 

703 

In 

Al,  Dx 

704 

Cmp 

Al,00h  /  dispatch  filter 

705 

Je 

Int_modem 

706 

Jmp 

Int_mo_no 

707 

:  Int-modem: 

708 

; 

dbg 

'M’,'S','  ' 

709 

Mov 

Dl,Mstat 

710 

In 

Al,dx  ;  read  MSR  content 

71 1 

Test 

Al,CDlvl  ;  carrier  present? 

712 

Jnz 

Msdsr  ;  yes,  test  for  DSR 

713 

Test 

OutSpec [si] , OutCdf  ;  no,  is  CD  ( 

Df  f 

line? 

714 

Jz 

Msdsr 

715 

Or 

InStat [si] , Of fLin 

716 

Msdsr : 

717 

Test 

Al,DSRlvl  ;  DSR  present? 

718 

Jnz 

Dsron  ;  yes,  handle  it 

719 

Test 

OutSpec [si] , OutDSR  ;  no,  is  DSR 

throttle' 

720 

Jz 

Dsrof f 

721 

Or 

OtStat [si] ,  LinDSR  ;  yes,  throttle 

down 

722 

Dsrof f : 

723 

Test 

OutSpec [si] , OutDrf  ;  is  DSR  off 

line? 

724 

Jz 

Mscts 

725 

Or 

InStat [si] ,OffLin  ;  yes,  set  flag 

726 

Jmp 

Short  Mscts 

Figure  6-1.  Continued. 
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727 

Dsron : 

728 

Test 

OtStat [si] , LinDSR 

;  throttled  for  DSR? 

729 

Jz 

Mscts 

730 

Xor 

OtStat [si] , LinDSR 

;  yes,  clear  it  out 

731 

Call 

Start—output 

732 

Mscts : 

733 

Test 

Al,CTSlvl 

CTS  present? 

734 

Jnz 

Ctson  ; 

yes,  handle  it 

735 

Test 

OutSpec [si] , OutCTS  ;  no,  is  CTS  throttle' 

736 

Jz 

Int_exit2 

737 

Or 

OtStat [si] , LinCTS 

;  yes,  shut  it  down 

738 

Jmp 

Short  Int_exit2 

739 

Ctson : 

740 

Test 

OtStat [si] , LinCTS 

;  throttled  for  CTS? 

741 

Jz 

Int_exit2 

742 

Xor 

OtStat [si] , LinCTS 

;  yes,  clear  it  out 

743 

Jmp 

Short  Int_exit1 

744 

Int_mo_ 

no: 

745 

Cmp 

Al,02h 

746 

Jne 

Int_tx_no 

747 

Int_txmit : 

748 

dbg 

’T’,'x’,'  * 

749 

Int_exit1 : 

750 

Call 

Start—output  ; 

try  to  send  another 

751 

Int_exit2 : 

752 

Jmp 

Int_exit 

753 

Int_tx_no: 

754 

Cmp 

Al,04h 

755 

Jne 

Int_rec_no 

756 

Int_receive : 

757 

; 

dbg 

’R' , 'x’ , •  ' 

758 

MOV 

Dx,port [si] 

759 

In 

A1 , dx  ; 

take  char  from  8250 

760 

Test 

OutSpec [si] ,OutXon  ;  is  XON/XOFF  enabled? 

761 

Jz 

Stuff_in  ; 

no 

762 

Cmp 

A1 , ' S '  And  0 1 FH  ; 

yes,  is  this  XOFF? 

763 

Jne 

Isq  ; 

no,  check  for  XON 

764 

Or 

OtStat [si] , LinXof 

;  yes,  disable  output 

765 

Jmp 

Int_exit2  ; 

don't  store  this  one 

766 

Isq: 

767 

Cmp 

Al, 'Q'  And  01 FH  ; 

is  this  XON? 

768 

Jne 

Stuff_in  ; 

no,  save  it 

769 

Test 

OtStat [si] , LinXof 

;  yes,  waiting? 

770 

Jz 

Int_exit2  ; 

no,  ignore  it 

771 

Xor 

OtStat [si] , LinXof 

;  yes,  clear  the  XOFF  bit 

772 

Jmp 

Int_exit1  ; 

and  try  to  resume  xmit 

773 

Int_rec 

_no : 

774 

Cmp 

Al, 06h 

775 

Jne 

Int_done 

776 

Int_rxstat : 

777 

; 

dbg 

•E',’R',’  * 

Figure  6-1.  Continued. 
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778 

Mov 

Dl, Lstat 

779 

In 

Al,  dx 

780 

Test 

InSpec [si] , 

InEpc 

return  them  as  codes? 

781 

Jz 

Nocode 

; 

no,  just  set  error  alarm 

782 

And 

Al, AnyErr 

; 

yes,  mask  off  all  but  error 

783 

Or 

Al,080h 

784 

Stuf f_in : 

785 

Call 

Put_in 

; 

put  input  char  in  buffer 

786 

Cmp 

Ah,  0 

; 

did  it  fit? 

787 

Je 

Int_exit3 

; 

yes,  all  OK 

788 

Or 

InStat [si] , 

LostDt 

;  no,  set  DataLost  bit 

789 

Int_exit3 : 

790 

Jmp 

Int_exit 

791 

Nocode : 

792 

Or 

InStat [si] , 

Badinp 

793 

Jmp 

Int_exit3 

794 

Int_done: 

795 

Clc 

796 

Jnc 

$+2 

797 

Mov 

Al,EOI 

/ 

all  done  now 

798 

Out 

PIC_b,Al 

799 

Pop 

Ds 

; 

restore  regs 

800 

Pop 

Di 

801 

Pop 

Dx 

802 

Pop 

Cx 

803 

Pop 

Bx 

804 

Pop 

Ax 

805 

Pop 

Si 

806 

Iret 

807 

808 

Start— output 

Proc  Near 

809 

Test 

OtStat [si] , 

Linidl 

;  Blocked? 

810 

Jnz 

Dont—Start 

; 

yes,  no  output 

811 

Mov 

Dx,port [si] 

; 

no,  check  UART 

812 

Mov 

Dl, Lstat 

813 

In 

Al,Dx 

814 

Test 

Al, xhre 

empty? 

815 

Jz 

Dont_start 

no 

816 

Call 

Get_out 

yes,  anything  waiting? 

817 

Or 

Ah,  Ah 

818 

Jnz 

Dont—Start 

; 

no 

819 

Mov 

Dl, RxBuf 

; 

yes,  send  it  out 

820 

Out 

Dx,  al 

821 

;  dbg 

's' , 'o' , ' 

822 

Dont_start : 

823 

ret 

824 

Start—output 

Endp 

825 

826 

Subttl  Initialization  Request  Routine 

827 

Page 

828 

Figure  6-1.  Continued. 
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829  :  init: 

Lea 

Di,  $ 

;  release  rest . .  . 

830  : 

Mov 

Es :Xfer [bx] , Di 

831  : 

Mov 

Es :Xseg[bx] ,Cs 

832  : 

833  : 

Mov 

Dx,Port [si] 

;  base  port 

834  : 

Mov 

Dl,Lctrl 

835  : 

Mov 

Al, Dlab 

;  enable  divisor 

836  : 

Out 

Dx,Al 

837  : 

Clc 

838  : 

Jnc 

$+2 

839  : 

Mov 

DI, RxBuf 

840  : 

Mov 

Ax, Baud [si] 

;  set  baud 

841  : 

Out 

Dx,Al 

842  : 

Clc 

843  : 

Jnc 

$+2 

844  : 

Inc 

Dx 

845  : 

Mov 

Al,Ah 

846  : 

Out 

Dx,Al 

847  : 

Clc 

848  : 

Jnc 

$+2 

849  : 

850  : 

Mov 

Dl,Lctrl 

;  set  LCR 

851  ; 

Mov 

Al,OtStat [si] 

;  from  table 

852  : 

Out 

Dx,Al 

853  : 

Mov 

OtStat [si] , 0 

;  clear  status 

854  ; 

Clc 

855  : 

Jnc 

$+2 

856  : 

Mov 

DI, IntEn 

;  lER 

857  : 

Mov 

Al,AllInt 

;  enable  ints  in  8250 

858  : 

Out 

Dx,Al 

859  : 

Clc 

860  : 

Jnc 

$+2 

861  : 

Mov 

Dl, Mctrl 

;  set  MCR 

862  : 

Mov 

Al, InStat [si] 

;  from  table 

863  : 

Out 

Dx,Al 

864  : 

Mov 

InStat  [si] , 0 

;  clear  status 

865  : 

866  :  ciRgs: 

Mov 

Dl,Lstat 

;  clear  LSR 

867  : 

In 

Al,  Dx 

868  : 

Mov 

Dl, RxBuf 

;  clear  RX  reg 

869  : 

In 

Al,  Dx 

870  : 

Mov 

Dl,Mstat 

;  clear  MSR 

871  : 

In 

Al,Dx 

872  : 

Mov 

Dl, Intid 

;  I ID  reg 

873  : 

In 

Al,Dx 

874  : 

In 

Al,  Dx 

875  : 

Test 

Al,  1 

;  int  pending? 

876  : 

Jz 

ClRgs 

;  yes,  repeat 

877  : 

878  : 

Cli 

879  : 

Xor 

Ax,  Ax 

;  set  int  vec 

Figure  6-1.  Continued. 
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880 

Mov 

Es,Ax 

881 

Mov 

Di, Vect [si] 

882 

Mov 

Ax, IsrAdr [si] 

883 

Stosw 

884 

Mov 

Es : [di] , cs 

885 

886 

In 

Al,PIC_e 

887 

And 

Al, 0E7h 

888 

Clc 

889 

Jnb 

$+2 

890 

Out 

PIC_e,Al 

891 

Sti 

892 

893 

Mov 

A1,E0I 

894 

Out 

PIC_b,Al 

895 

896 

;  dbg 

•D’, ’I', ’  • 

897 

Jmp 

Zexit 

898 

899 

Driver  Ends 

900 

End 

Figure  6-1.  Continued. 


from  table 


get  8259 
comi /2  mask 


now  send  EOI  just  in  case 


driver  installed 


The  first  part  of  the  driver  source  code  (after  the  necessary  MASM  housekeeping  details 
in  lines  1  through  8)  is  a  commented-out  macro  definition  (lines  10  through  32).  This 
macro  is  used  only  during  debugging  and  is  part  of  a  debugging  technique  that  requires 
no  sophisticated  hardware  and  no  more  complex  debugging  program  than  the  venerable 
DEBUG.COM.  (Debugging  techniques  are  discussed  after  the  presentation  of  the  driver 
program  itself.) 

Definitions 

The  actual  driver  source  program  consists  of  three  sets  of  EQU  definitions  (lines  34 
through  194),  followed  by  the  modular  code  and  data  areas  (lines  197  through  900).  The 
first  set  of  definitions  (lines  34  through  82)  gives  symbolic  names  to  the  permissible  values 
for  MS-DOS  device-driver  control  bits  and  the  device-driver  structures. 

The  second  set  of  definitions  (lines  84  through  145)  assigns  names  to  the  ports  and  bit 
values  that  are  associated  with  the  IBM  hardware — both  the  8259  PIC  and  the  8250  UART 
The  third  set  of  definitions  (lines  147  through  194)  assigns  names  to  the  control  values  and 
structures  associated  with  this  driver. 

The  definition  method  used  here  is  recommended  for  all  drivers.  To  move  this  driver  from 
the  IBM  architecture  to  some  other  hardware,  the  major  change  required  to  the  program 
would  be  reassignment  of  the  port  addresses  and  bit  values  in  lines  84  through  145. 

The  control  values  and  structures  for  this  specific  driver  (defined  in  the  third  EQU  set) 
provide  the  means  by  which  the  separate  support  program  can  modify  the  actions  of  each 
of  the  two  logical  drivers.  They  also  permit  the  driver  to  return  status  information  to  both 
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the  support  program  and  the  using  program  as  necessary.  Only  a  few  features  are  imple¬ 
mented,  but  adequate  space  for  expansion  is  provided.  The  addition  of  a  few  more  defini¬ 
tions  in  this  area  and  one  or  two  extra  procedures  in  the  code  section  would  do  all  that  is 
necessary  to  extend  the  driver’s  capabilities  to  such  features  as  automatic  expansion  of 
tab  characters,  case  conversion,  and  so  forth,  should  they  be  desired. 

Headers  and  structure  tables 

The  driver  code  itself  starts  with  a  linked  pair  of  device-driver  header  blocks,  one  for 
ASYl  (lines  201  through  207)  and  the  other  for  ASY2  (lines  208  through  213).  Following 
the  headers,  in  lines  215  through  236,  are  a  commented-out  space  reservation  used  by  the 
debugging  procedure  (line  215),  the  pointer  to  the  command  packet  (line  219),  and  the 
baud-rate  conversion  table  (lines  221  through  236). 

The  conversion  table  is  followed  by  structure  tables  containing  all  data  unique  to  ASYl 
(lines  239  through  242)  and  ASY2  (lines  244  through  247).  After  the  structure  tables, 
buffer  areas  are  reserved  in  lines  249  through  254.  One  input  buffer  and  one  output  buffer 
are  reserved  for  each  port.  All  buffers  are  the  same  size;  for  simplicity,  buffer  size  is  given  a 
name  (at  line  249)  so  that  it  can  be  changed  by  editing  a  single  line  of  the  program. 

The  size  is  arbitrary  in  this  case,  but  if  file  transfers  are  anticipated,  the  buffer  should  be 
able  to  hold  at  least  2  seconds’  worth  of  data  (240  bytes  at  1200  bps)  to  avoid  data  loss  dur¬ 
ing  writes  to  disk.  Whatever  size  is  chosen  should  be  a  power  of  2  for  simple  pointer  arith¬ 
metic  and,  if  video  display  is  intended,  should  not  be  less  than  8  bytes,  to  prevent  losing 
characters  when  the  screen  scrolls. 

If  additional  ports  are  desired,  more  headers  can  be  added  after  line  213;  corresponding 
structure  tables  for  each  driver,  plus  matching  pairs  of  buffers,  would  also  be  necessary. 
The  final  part  of  this  area  is  the  dispatch  table  (lines  256  through  284),  which  lists  offsets 
of  all  request  routines  in  the  driver;  its  use  is  discussed  below. 

Strategy  and  Request  routines 

With  all  data  taken  care  of,  the  program  code  begins  at  the  Strategy  routine  (lines  289 
through  296),  which  is  used  by  both  ports.  This  code  saves  the  command  packet  address 
passed  to  it  by  MS-DOS  for  use  by  the  Request  routine  and  returns  to  MS-DOS. 

The  Request  routines  (lines  298  through  567)  are  also  shared  by  both  ports,  but  the  two 
drivers  are  distinguished  by  the  address  placed  into  the  SI  register.  This  address  points  to 
the  structure  table  that  is  unique  to  each  port  and  contains  such  data  as  the  port’s  base 
address,  the  associated  hardware  interrupt  vector,  the  interrupt  service  routine  offset 
within  the  driver’s  segment,  the  base  offsets  of  the  input  and  output  buffers  for  that  port, 
two  pointers  for  each  of  the  buffers,  and  the  input  and  output  status  conditions  (including 
baud  rate)  for  the  port.  The  only  difference  between  one  port’s  driver  and  the  other’s  is 
the  data  pointed  to  by  SI;  all  Request  routine  code  is  shared  by  both  ports. 

Each  driver’s  Request  routine  has  a  unique  entry  point  (at  line  298  for  ASYl  and  at  line  303 
for  ASY2')  that  saves  the  original  content  of  the  SI  register  and  then  loads  it  with  the  ad¬ 
dress  of  the  structure  table  for  that  driver.  The  routines  then  join  as  a  common  stream  at 
line  307  iGen_request). 
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This  common  code  preserves  all  other  registers  used  (lines  309  through  318),  sets  DS 
equal  to  CS  (lines  319  and  320),  retrieves  the  command-packet  pointer  saved  by  the  Strat¬ 
egy  routine  (line  321),  uses  the  pointer  to  get  the  command  code  (line  323),  uses  the  code 
to  calculate  an  offset  into  a  table  of  addresses  (lines  324  through  326),  and  performs  an  in¬ 
dexed  jump  (lines  322  and  327)  by  way  of  the  dispatch  table  (lines  256  through  284)  to  the 
routine  that  executes  the  requested  command  (at  line  336, 360, 389, 404, 4l4, 421, 441, 453, 
500,  or  829). 

Although  the  device-driver  specifications  for  MS-DOS  version  3.2  list  command  request 
codes  ranging  from  0  to  24,  not  all  are  used.  Earlier  versions  of  MS-DOS  permitted  only  0 
to  12  (versions  2.x)  or  0  to  l6  (versions  3.0  and  3.1)  codes.  In  this  driver,  all  24  codes  are 
accounted  for;  those  not  implemented  in  this  driver  return  a  DONE  and  NO  ERROR  status 
to  the  caller.  Because  the  Request  routine  is  called  only  by  MS-DOS  itself,  there  is  no  check 
for  invalid  codes.  Actually,  because  the  header  attribute  bits  are  not  set  to  specify  that 
codes  13  through  24  are  valid,  the  24  bytes  occupied  by  their  table  entries  (lines  273 
through  284)  could  be  saved  by  omitting  the  entries.  They  are  included  only  to  show 
how  nonexistent  commands  can  be  accommodated. 

Immediately  following  the  dispatch  indexed  jump,  at  lines  329  through  353  within  the 
same  PROC  declaration,  is  the  common  code  used  by  all  Request  routines  to  store  status 
information  in  the  command  packet,  restore  the  registers,  and  return  to  the  caller.  The 
alternative  entry  points  for  BUSY  status  (line  332),  NO  ERROR  status  (line  338),  or  an  error 
code  (in  the  AX  register  at  entry  to  Exity  line  339)  not  only  save  several  bytes  of  redundant 
code  but  also  improve  readability  of  the  code  by  providing  unique  single  labels  for  BUSY, 
NO  ERROR,  and  ERROR  return  conditions. 

All  of  the  Request  routines,  except  for  the  Init  code  at  line  829,  immediately  follow  the 
dispatching  shell  in  lines  358  through  568.  Each  is  simplified  to  perform  just  one  task,  such 
as  read  data  in  or  write  data  out.  The  Read  routine  (lines  360  through  385)  is  typical:  First, 
the  requested  byte  count  and  user’s  buffer  address  are  obtained  from  the  command 
packet.  Next,  the  pointer  to  the  command  packet  is  saved  with  a  PUSH  instruction,  so  that 
the  ES  and  BX  registers  can  be  used  for  a  pointer  to  the  port’s  input  buffer. 

Before  the  Get_in  routine  that  actually  accesses  the  input  buffer  is  called,  the  input  status 
byte  is  checked  (line  368).  If  an  error  condition  is  flagged,  lines  370  through  373  clear  the 
status  flag,  flush  the  saved  pointers  from  the  stack,  and  jump  to  the  error-return  exit  from 
the  driver.  If  no  error  exists,  line  375  calls  Get_in  to  access  the  input  buffer  and  lines  376 
and  377  determine  whether  a  byte  was  obtained.  If  a  byte  is  found,  it  is  stored  in  the  user’s 
buffer  by  line  378,  and  line  379  loops  back  to  get  another  byte  until  the  requested  count 
has  been  obtained  or  until  no  more  bytes  are  available.  In  practice,  the  count  is  an  upper 
limit  and  the  loop  is  normally  broken  when  data  runs  out. 

No  matter  how  it  happens,  control  eventually  reaches  the  Got_all  routine  and  lines  381 
and  382,  where  the  saved  pointers  to  the  command  packet  are  restored  from  the  stack. 
Lines  383  and  384  adjust  the  count  value  in  the  packet  to  reflect  the  actual  number  of  bytes 
obtained.  Finally,  line  385  jumps  to  the  normal,  no-error  exit  from  the  driver. 
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Buffering 

Both  buffers  for  each  driver  are  of  the  type  known  as  circular,  or  ring,  buffers.  Effectively, 
such  a  buffer  is  endless;  it  is  accessed  via  pointers,  and  when  a  pointer  increments  past  the 
end  of  the  buffer,  the  pointer  returns  to  the  buffer’s  beginning.  Two  pointers  are  used  here 
for  each  buffer,  one  to  put  data  into  it  and  one  to  get  data  out.  The  get  pointer  always 
points  to  the  next  byte  to  be  read;  the  put  pointer  points  to  where  the  next  byte  will  be 
written,  just  past  the  last  byte  written  to  the  buffer. 

If  both  pointers  point  to  the  same  byte,  the  buffer  is  empty;  the  next  byte  to  be  read  has 
not  yet  been  written.  The  full-buffer  condition  is  more  difficult  to  test  for:  The  put  pointer 
is  incremented  and  compared  with  the  get  pointer;  if  they  are  equal,  doing  a  write  would 
force  a  false  buffer-empty  condition,  so  the  buffer  must  be  full. 

All  buffer  manipulation  is  done  via  four  procedures  (lines  569  through  674).  Put^out 
(lines  572  through  596)  writes  a  byte  to  the  driver’s  output  buffer  or  returns  a  buffer-full 
indication  by  setting  AH  to  OFFH.  Get^out  (lines  598  through  622)  gets  a  byte  from  the 
output  buffer  or  returns  OFFH  in  AH  to  indicate  that  no  byte  is  available.  Put_  in  (lines  624 
through  648)  and  Get^in  (lines  650  through  674)  do  exactly  the  same  as  Put_out  and 
Get_out,  but  for  the  input  buffer.  These  procedures  are  used  both  by  the  Request  routines 
and  by  the  hardware  interrupt  service  routine  (ISR). 

Interrupt  service  routines 

The  most  complex  part  of  this  driver  is  the  ISR  (lines  676  through  806),  which  decides 
which  of  the  four  possible  services  for  a  port  is  to  be  performed  and  where.  Like  the 
Request  routines,  the  ISR  provides  unique  entry  points  for  each  port  (line  679  for  ASYl  and 
line  685  for  ASY2')\  these  entry  points  first  preserve  the  SI  register  and  then  load  it  with  the 
address  of  the  port’s  structure  table.  With  SI  indicating  where  the  actions  are  to  be  per¬ 
formed,  the  two  entries  then  merge  at  line  690  into  common  code  that  first  preserves  all 
registers  to  be  used  by  the  ISR  (lines  690  through  698)  and  then  tests  for  each  of  the  four 
possible  types  of  service  and  performs  each  requested  action. 

Much  of  the  complexity  of  the  ISR  is  in  the  decoding  of  modem-status  conditions.  Because 
the  resulting  information  is  not  used  by  this  driver  (although  it  could  be  used  to  prevent 
attempts  to  transmit  while  off  line),  these  ISR  options  can  be  removed  so  that  only  the 
Transmit  and  Receive  interrupts  are  serviced.  To  do  this,  Allint  (at  line  145)  should  be 
changed  from  the  OR  of  all  four  bits  to  include  only  the  transmit  and  receive  bits  (03H, 
orOOOOOOllB). 

The  transmit  and  receive  portions  of  the  ISR  incorporate  XON/XOFF  flow  control  (for 
transmitted  data  only)  by  default.  This  control  is  done  at  the  ISR  level,  rather  than  in  the 
using  program,  to  minimize  the  time  required  to  respond  to  an  incoming  XOFF  signal. 
Presence  of  the  flow-control  decisions  adds  complexity  to  what  would  otherwise  be 
extremely  simple  actions. 

Flow  control  is  enabled  or  disabled  by  setting  the  OutSpec  word  in  the  structure  table 
with  the  Driver  Status  utility  (presented  later)  via  the  lOCTL  function  (Interrupt  21H  Func¬ 
tion  44H).  When  flow  control  is  enabled,  any  XOFF  character  (IIH)  that  is  received  halts 
all  outgoing  data  until  XON  (13H)  is  received.  No  XOFF  or  XON  is  retained  in  the  input 
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buffer  to  be  sent  on  to  any  program,  although  all  patterns  other  than  XOFF  and  XON  are 
passed  through  by  the  driver.  When  flow  control  is  disabled,  the  driver  passes  all  patterns 
in  both  directions.  For  binary  file  transfer,  flow  control  must  be  disabled. 

The  transmit  action  is  simple:  The  code  merely  calls  the  Start^output  procedure  at  line 
750.  Start_output  is  described  in  detail  below. 

The  receive  action  is  almost  as  simple  as  transmit,  except  for  the  flow-control  testing.  First, 
the  ISR  takes  the  received  byte  from  the  UART  (lines  758  and  759)  to  avoid  any  chance  of 
an  overrun  error.  The  ISR  then  tests  the  input  specifier  (at  line  760)  to  determine  whether 
flow  control  is  in  effect.  If  it  is  not,  processing  jumps  directly  to  line  784  to  store  the 
received  byte  in  the  input  buffer  with  Put_in  (line  785). 

If  flow  control  is  active,  however,  the  received  byte  is  compared  with  the  XOFF  character 
(lines  762  through  765).  If  the  byte  matches,  output  is  disabled  and  the  byte  is  ignored.  If 
the  byte  is  not  XOFF,  it  is  compared  with  XON  (lines  766  through  768).  If  it  is  not  XON 
either,  control  jumps  to  line  784.  If  the  byte  is  XON,  output  is  re-enabled  if  it  was  disabled. 
Regardless,  the  XON  byte  itself  is  ignored. 

When  control  reaches  Stuff^in  at  line  784,  Put^in  is  called  to  store  the  received  byte  in 
the  input  buffer.  If  there  is  no  room  for  it,  a  lost-databit  is  set  in  the  input  status  flags  (line 
788);  otherwise,  the  receive  routine  is  finished. 

If  the  interrupt  was  a  line-status  action,  the  LSR  is  read  (lines  776  through  779).  If  the  input 
specifier  so  directs,  the  content  is  converted  to  an  IBM  PC  extended  graphics  character  by 
setting  bit  7  to  1  and  the  character  is  stored  in  the  input  buffer  as  if  it  were  a  received  byte. 
Otherwise,  the  Line  Status  interrupt  merely  sets  the  generic  Badinp  error  bit  in  the  input 
status  flags,  which  can  be  read  with  the  lOCTL  Read  function  of  the  driver. 

When  all  ISR  action  is  complete,  lines  794  through  806  restore  machine  conditions  to  those 
existing  at  the  time  of  the  interrupt  and  return  to  the  interrupted  procedure. 

The  Start^output  routine 

Start^output  (lines  808  through  824)  is  a  routine  that,  like  the  four  buffer  procedures,  is 
used  by  both  the  Request  routines  and  the  ISR.  Its  purpose  is  to  initiate  transmission  of  a 
byte,  provided  that  output  is  not  blocked  by  flow  control,  the  UART  Transmit  Holding 
Register  is  empty,  and  a  byte  to  be  transmitted  exists  in  the  output  ring  buffer.  This  routine 
uses  the  Get_out  buffer  routine  to  access  the  buffer  and  determine  whether  a  byte  is  avail¬ 
able.  If  all  conditions  are  met,  the  byte  is  sent  to  the  UART  holding  register  by  lines  819 
and  820. 

The  Initialization  Request  routine 

The  Initialization  Request  routine  (lines  829  through  897)  is  critical  to  successful  operation 
of  the  driver.  This  routine  is  placed  last  in  the  package  so  that  it  can  be  discarded  as  soon 
as  it  has  served  its  purpose  by  installing  the  driver.  It  is  essential  to  clear  each  register  of 
the  8250  by  reading  its  contents  before  enabling  the  interrupts  and  to  loop  through  this 
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action  until  the  8250  finally  shows  no  requests  pending.  The  strange  Clc  jnc  $-i-2 
sequence  that  appears  repeatedly  in  this  routine  is  a  time  delay  required  by  high-speed 
machines  (6  MHz  and  up)  so  that  the  8250  has  time  to  settle  before  another  access  is 
attempted;  the  delay  does  no  harm  on  slower  machines. 

Using  COMDVR 

The  first  step  in  using  this  device  driver  is  assembling  it  with  the  Microsoft  Macro  Assem¬ 
bler  (MASM).  Next,  use  the  Microsoft  Object  Linker  (LINK)  to  create  a  .EXE  file.  Convert 
the  .EXE  file  into  a  binary  image  file  with  the  EXE2BIN  utility.  Finally,  include  the  line 
DEVICE =COMDVR.SYS  in  the  CONFIG.SYS  file  so  that  COMDVR  will  be  installed  when 
the  system  is  restarted. 

Note:  The  number  and  colon  at  the  beginning  of  each  line  in  the  program  listings  in  this 
article  are  for  reference  only  and  should  not  be  included  in  the  source  file. 

Figure  6-2  shows  the  sequence  of  actions  required,  assuming  that  EDLIN  is  used  for 
modifying  (or  creating)  the  CONFIG.SYS  file  and  that  all  commands  are  issued  from  the 
root  directory  of  the  boot  drive. 

Creating  the  driver: 

C>MASM  COMDVR;  <Enter> 

OLINK  COMDVR;  <Enter> 

OEXE2BIN  COMDVR.EXE  COMDVR. SYS  <Enter> 

Modifying  CONFIG.SYS  (^2  «  press  Ctrl-2): 

OEDLIN  CONFIG.SYS  <Enter> 

*#I  <Enter> 

*DEVICE=COMDVR.SYS  <Enter> 

*^Z  <Enter> 

*E  <Enter> 

Figure  6-2.  Assembling,  linking,  and  installing  COMDVR. 

Because  the  devices  installed  by  COMDVR  do  not  use  the  standard  MS-DOS  device  names, 
no  conflict  occurs  with  any  program  that  uses  conventional  port  references.  Such  a  pro¬ 
gram  will  not  use  the  driver,  and  no  problems  should  result  if  the  program  is  well  behaved 
and  restores  all  interrupt  vectors  before  returning  to  MS-DOS. 

Device-driver  debugging  techniques 

The  debugging  of  device  drivers,  like  debugging  for  any  part  of  MS-DOS  itself,  is  more 
difficult  than  normal  program  checking  because  the  debugging  program,  DEBUG.COM  or 
DEBUG.EXE,  itself  uses  MS-DOS  functions  to  display  output.  When  these  functions  are 
being  checked,  their  use  by  DEBUG  destroys  the  data  being  examined.  And  because 
MS-DOS  always  saves  its  return  address  in  the  same  location,  any  call  to  a  function  from 
inside  the  operating  system  usually  causes  a  system  lockup  that  can  be  cured  only  by 
shutting  the  system  down  and  powering  up  again. 
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One  way  to  overcome  this  difficulty  is  to  purchase  costly  debugging  tools.  An  easier 
way  is  to  bypass  the  problem:  Instead  of  using  MS-DOS  functions  to  track  program  opera¬ 
tion,  write  data  directly  to  video  RAM,  as  in  the  macro  DBG  (lines  10  through  32  of 
COMDVR.ASM). 

This  macro  is  invoked  with  a  three-character  parameter  string  at  each  point  in  the  pro¬ 
gram  a  progress  report  is  desired.  Each  invocation  has  its  own  unique  three-character 
string  so  that  the  sequence  of  actions  can  be  read  from  the  screen.  When  invoked,  DBG 
expands  into  code  that  saves  all  registers  and  then  writes  the  three-character  string  to 
video  RAM.  Only  the  top  10  lines  of  the  screen  (800  characters,  or  l600  bytes)  are  used: 

The  macro  uses  a  single  far  pointer  to  the  area  and  treats  the  video  RAM  like  a  ring  buffer. 

The  pointer,  Dbgptr  (line  215),  is  set  up  for  use  with  the  monochrome  adapter  and  points 
to  location  B000:0000H;  to  use  a  CGA  or  EGA  (in  CGA  mode),  the  location  should  be 
changed  to  B800:0000H. 

Most  of  the  frequently  used  Request  routines,  such  as  Read  and  Write,  have  calls  to  DBG 
as  their  first  lines  (for  example,  lines  361  and  422).  As  shown,  these  calls  are  commented 
out,  but  for  debugging,  the  source  file  should  be  edited  so  that  all  the  calls  and  the  macro 
itself  are  enabled. 

With  DBG  active,  the  top  10  lines  of  the  display  are  overwritten  with  a  continual  sequence 
of  reports,  such  ^sRRTx,  put  directly  into  video  RAM.  Because  MS-DOS  functions  are  not 
used,  no  interference  with  the  driver  itself  can  occur. 

Although  this  technique  prevents  normal  use  of  the  system  during  debugging,  it  greatly 
simplifies  the  problem  of  knowing  what  is  happening  in  time-critical  areas,  such  as  hard¬ 
ware  interrupt  service.  In  addition,  all  invocations  of  DBG  in  the  critical  areas  are  in  con¬ 
ditional  code  that  is  executed  only  when  the  driver  is  working  as  it  should. 

Failure  to  display  the  pi  message,  for  instance,  indicates  that  the  received-data  hardware 
interrupt  is  not  being  serviced,  and  absence  of  go  after  an  Ix  report  shows  that  data  is  not 
being  sent  out  as  it  should. 

Of  course,  once  debugging  is  complete,  the  calls  to  DBG  should  be  deleted  or  commented 
out.  Such  calls  are  usually  edited  out  of  the  source  code  before  release.  In  this  case,  they 
remain  to  demonstrate  the  technique  and,  most  particularly,  to  show  placement  of  the  calls 
to  provide  maximum  information  with  minimal  clutter  on  the  screen. 

A  simple  modem  engine 

The  second  part  of  this  package  is  the  modem  engine  itself  (ENGINE.ASM),  shown  in  the 
listing  in  Figure  6-3.  The  main  loop  of  this  program  consists  of  only  a  dozen  lines  of  code 
(lines  9  through  20).  Of  these,  five  (lines  9  through  13)  are  devoted  to  establishing  initial 
contact  between  the  program  and  the  serial-port  driver  and  two  (lines  19  and  20)  are  for 
returning  to  command  level  at  the  program’s  end. 

Thus,  only  five  lines  of  code  (lines  14  through  18)  actually  carry  out  the  bulk  of  the  pro¬ 
gram  as  far  as  the  main  loop  is  concerned.  Four  of  these  lines  are  calls  to  subroutines  that 
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get  and  put  data  from  and  to  the  console  and  the  serial  port;  the  fifth  is  the  JMP  that  closes 
the  loop.  This  structure  underscores  the  fact  that  a  basic  modem  engine  is  simply  a  data- 
transfer  loop. 


1 

TITLE 

engine 

2 

3 

CODE 

SEGMENT 

PUBLIC  'CODE' 

4 

5 

ASSUME 

CS:CODE,DS 

; : CODE, ES : CODE, SS : CODE 

6 

7 

ORG 

OlOOh 

8 

9 

START : 

mov 

dx, offset 

devnm  ; 

open  named  device  (ASY1 ) 

10 

mov 

ax,3d02h 

1 1 

int 

21h 

12 

mov 

handle, ax 

; 

save  the  handle 

13 

jc 

quit 

14 

alltim: 

call 

getmdm 

; 

main  engine  loop 

15 

call 

putcrt 

16 

call 

getkbd 

17 

call 

putmdm 

18 

jmp 

alltim 

19 

quit : 

mov 

ah, 4ch 

/ 

come  here  to  quit 

20 

int 

21h 

21 

22 

getmdm 

proc 

; 

get  input  from  modem 

23 

mov 

cx, 256 

24 

mov 

bx, handle 

25 

mov 

dx, offset 

mbufr 

26 

mov 

ax, 3F00h 

27 

int 

21h 

28 

jc 

quit 

29 

mov 

mdlen, ax 

30 

ret 

31 

getmdm 

endp 

32 

33 

getkbd 

proc 

get  input  from  keyboard 

34 

mov 

kblen, 0 

first  zero  the  count 

35 

mov 

ah,  1 1 

key  pressed? 

36 

int 

21h 

37 

inc 

al 

38  : 

jnz 

nogk 

; 

no 

39 

mov 

ah,  7 

; 

yes,  get  it 

40 

int 

21h 

41 

cmp 

al,3 

; 

was  it  Ctrl-C? 

42 

je 

quit 

; 

yes,  get  out 

43 

mov 

kbuf r, al 

; 

no,  save  it 

44 

inc 

kblen 

45 

cmp 

al,  13 

; 

was  it  Enter? 

46 

jne 

nogk 

; 

no 

Figure  6-3.  ENGINE.  ASM.  (more) 
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47 

mov 

byte  ptr  kbufr+1 , 

10  ; 

yes,  add  LF 

48 

inc 

kblen 

49 

nogk: 

ret 

50 

getkbd 

endp 

51 

52 

putmdm 

proc 

; 

put 

output  to 

modem 

53 

mov 

cx, kblen 

54 

jcxz 

nopm 

55 

mov 

bx,  handle 

56 

mov 

dx, offset  kbufr 

57 

mov 

ax, 4000h 

58 

int 

21h 

59 

jc 

quit 

60 

nopm: 

ret 

61 

putmdm 

endp 

62 

63 

putcrt 

proc 

put 

output  to 

CRT 

64 

mov 

cx, mdlen 

65 

jcxz 

nope 

66 

mov 

bx,  1 

67 

mov 

dx, offset  mbufr 

68 

mov 

ah,40h 

69 

int 

21h 

70 

jc 

quit 

71 

nope: 

ret 

72 

putcrt 

endp 

73 

74 

devnm 

db 

'ASY1’,0 

miscellaneous 

data  and  buffers 

75 

handle 

dw 

0 

76 

kblen 

dw 

0 

77 

mdlen 

dw 

0 

78 

mbufr 

db 

256  dup  (0) 

79 

kbufr 

db 

80  dup  (0) 

80 

81 

CODE 

ENDS 

82 

END 

START 

Figure  6-3.  Continued. 


Because  the  details  of  timing  and  data  conversion  are  handled  by  the  driver  code,  each 
of  the  four  subroutines  is — to  show  just  how  simple  the  whole  process  is — essentially  a 
buffered  interface  to  the  MS-DOS  Read  File  or  Device  or  Write  File  or  Device  routine. 

For  example,  the  getmdm  procedure  (lines  22  through  31)  asks  MS-DOS  to  read  a  max¬ 
imum  of  256  bytes  from  the  serial  device  and  then  stores  the  number  actually  read  in  a 
word  named  mdlen.  The  driver  returns  immediately,  without  waiting  for  data,  so  the  nor¬ 
mal  number  of  bytes  returned  is  either  0  or  1.  If  screen  scrolling  causes  the  loop  to  be 
delayed,  the  count  might  be  higher,  but  it  should  never  exceed  about  a  dozen  characters. 

When  called,  the  putcrt  procedure  (lines  63  through  72)  checks  the  value  in  mdlen.  If 
the  value  is  zero,  putcrt  does  nothing;  otherwise,  it  asks  MS-DOS  to  write  that  number  of 
bytes  from  mbufr  (where  getmdm  put  them)  to  the  display,  and  then  it  returns. 
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Similarly,  getkbd  gets  keystrokes  from  the  keyboard,  stores  them  in  kbufr,  and  posts  a 
count  in  kblen\  putmdm  checks  kblen  and,  if  the  count  is  not  zero,  sends  the  required 
number  of  bytes  from  kbufr  to  the  serial  device. 

Note  that  getkbd  does  not  use  the  Read  File  or  Device  function,  because  that  would  wait 
for  a  keystroke  and  the  loop  must  never  wait  for  reception.  Instead,  it  uses  the  MS-DOS 
functions  that  test  keyboard  status  (OBH)  and  read  a  key  without  echo  (07H).  In  addition, 
special  treatment  is  given  to  the  Enter  key  (lines  45  through  48):  A  linefeed  is  inserted  in 
kbufr  immediately  behind  Enter  and  kblen  is  set  to  2. 

A  Ctrl-C  keystroke  ends  program  operation;  it  is  detected  in  getkbd  (line  41)  and  causes 
immediate  transfer  to  the  quit  label  (line  19)  at  the  end  of  the  main  loop.  Because  ENGINE 
uses  only  permanently  resident  routines,  there  is  no  need  for  any  uninstallation  before 
returning  to  the  MS-DOS  command  prompt. 

ENGINE.ASM  is  written  to  be  used  as  a  .COM  file.  Assemble  and  link  it  the  same  as 
COMDVR.SYS  (Figure  6-2)  but  use  the  extension  COM  instead  of  SYS;  no  change  to 
CONFIG.SYS  is  needed. 

The  driver-status  utility:  CDVUTL.C 

The  driver-status  utility  program  CDVUTL.C,  presented  in  Figure  6-4,  permits  either  of 
the  two  drivers  iASYl  andASY2)  to  be  reconfigured  after  being  installed,  to  suit  different 
needs.  After  one  of  the  drivers  has  been  specified  (port  1  or  port  2),  the  baud  rate,  word 
length,  parity,  and  number  of  stop  bits  can  be  changed;  each  change  is  made  indepen¬ 
dently,  with  no  effect  on  any  of  the  other  characteristics.  Additionally,  flow  control  can  be 
switched  between  two  types  of  hardware  handshaking — the  software  XON/XOFF  control 
or  disabled — and  error  reporting  can  be  switched  between  character-oriented  and 
message-oriented  operation. 


/*  cdvutl.c  -  COMDVR  Utility 

*  Jim  Kyle  -  1  987 

*  for  use  with  COMDVR.SYS  Device  Driver 
*/ 


linclude  <stdio.h> 
#include  <conio.h> 
#include  <stdlib.h> 


/*  i/o  definitions  */ 
/*  special  console  i/o  */ 
/*  misc  definitions  */ 


9 

10 

1 1 

12 

13 

:  #include  <dos 

.h> 

defines  intdosO 

*/ 

/* 

the  : 

following  define 

the 

driver  status  bits 

*/ 

#def ine 

HWINT 

0x0800 

/* 

MCR, 

first 

word,  HW  Ints  gated 

*/ 

14 

#define 

o_DTR 

0x0200 

/* 

MCR, 

first 

word,  output 

DTR 

*/ 

15 

16 

17 

#def ine 

o_RTS 

0x0100 

/* 

MCR, 

first 

word,  output 

RTS 

*/ 

#define 

m_PG 

0x0010 

/* 

LCR, 

first 

word,  parity 

ON 

*/ 

18 

#def ine 

ni_PE 

0x0008 

/* 

LCR, 

first 

word,  parity 

EVEN 

*/ 

Figure  6-4.  CDVUTL.C 
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19 

#define 

m_XS 

0x0004 

/♦  LCR,  first  word,  2  stop 

bits 

♦/ 

20 

#define 

m-WL 

0x0003 

/♦  LCR,  first  word,  wordlen  mask 

*/ 

21 

22 

#define 

i_CD 

0x8000 

/*  MSR,  2nd  word.  Carrier 

Detect 

*/ 

23 

#define 

i_RI 

0x4000 

/*  MSR,  2nd  word.  Ring  Indicator 

*/ 

24 

#define 

i_DSR 

0x2000 

/*  MSR,  2nd  word.  Data  Set 

Ready 

*/ 

25 

#define 

i_CTS 

0x1 000 

/*  MSR,  2nd  word.  Clear  to 

Send 

*/ 

26 

27 

#define 

1_SRE 

0x0040 

/*  LSR,  2nd  word,  Xmtr  SR 

Empty 

*/ 

28 

#define 

1_HRE 

0x0020 

/*  LSR,  2nd  word,  Xmtr  HR 

Empty 

*/ 

29 

#define 

1_BRK 

0x0010 

/♦  LSR,  2nd  word.  Break  Received 

*/ 

30 

Idefine 

1_ER1 

0x0008 

/*  LSR,  2nd  word,  FrmErr 

♦/ 

31 

#define 

1_ER2 

0x0004 

/*  LSR,  2nd  word,  ParErr 

*/ 

32 

#define 

1_ER3 

0x0002 

/♦  LSR,  2nd  word,  OveRun 

*/ 

33 

#define 

1_RRF 

0x0001 

/♦  LSR,  2nd  word,  Rcvr  DR 

Full 

*/ 

34 

35 

/* 

now  define 

CLS  string  for  ANSI. SYS 

*/ 

36 

#define 

CLS 

”\033[2J' 

37 

38 

FILE  *  dvp; 

39 

union  REGS  rvs; 

40 

int  iobf  [  5  ; 

; 

41 

42 

main  {) 

43 

{  cputs 

(  "NnCDVUTL  -  COMDVR  Utility  Version  1.0  -  1987\n 

”  ); 

44 

disp 

0; 

/♦  do  dispatch  loop 

*/ 

45 

} 

46 

47 

disp  0 

/*  dispatcher;  infinite  loop 

*/ 

48 

{  int  c 

49 

u; 

50 

u  =  1, 

51 

while 

(  1  ) 

52 

{  cputs  ( 

''\r\n\tCommand  (?  for  help):  ”  ); 

53 

switch 

tolower 

c  =  getche  ()))  /*  dispatch 

*/ 

54 

{ 

55 

case 

1  •  : 

/*  select  port  1 

*/ 

56 

fclose  (  dvp  ) 

; 

57 

dvp 

=  fopen  ( 

"ASYI",  ”rb+"  ); 

58 

u  =  In¬ 

59 

break; 

60 

61 

case 

2'  : 

/*  select  port  2 

*/ 

62 

fclose  (  dvp  ) 

; 

63 

dvp 

=  fopen  ( 

”ASY2",  "rb+"  ); 

64 

u  = 

2; 

65 

break; 

66 

67 

case 

b'  : 

/*  set  baud  rate 

*/ 

68 

if 

iobf  [  4 

)  ==  300  ) 

69 

iobf  [  4  ]  = 

1200; 

Figure  6-4.  Continued.  (more) 
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70 

else 

71 

if  (  iobf  [  4  ]  ==  1200 

) 

72 

iobf  [  4  ]  =  2400; 

73 

else 

74 

if  {  iobf  [  4  )  ==  2400 

) 

75 

iobf  [  4  ]  =  9600; 

76 

else 

77 

iobf  [  4  ]  =  300; 

78 

iocwr  0 ; 

79 

break; 

80 

81 

case  'e'  : 

/*  set  parity  even 

*/ 

82 

iobf  [  0  ]  1=  (  m-PG  +  m_PE  >; 

83 

iocwr  ( ) ; 

84 

break; 

85 

86 

case  'f  : 

/*  toggle  flow  control 

*/ 

87 

if  {  iobf  [  3  ]  ==  1  ) 

88 

iobf  [  3  ]  =  2; 

89 

else 

90 

if  {  iobf  [  3  ]  ==  2  ) 

91 

iobf  [  3  ]  =  4; 

92 

else 

93 

if  (  iobf  [  3  1  ==  4  ) 

94 

iobf  [31=0; 

95 

else 

96 

iobf  [  3  ]  =  1; 

97 

iocwr  ( ) ; 

98 

break; 

99 

100 

case  'i'  : 

/*  initialize  MCR/LCR  to  8N1 

:  */ 

101 

iobf  c  0  ]  =  (  HWINT  +  o_DTR  +  o_RTS  +  in_WL  )  ; 

102 

iocwr  ( ) ; 

103 

break; 

104 

105 

case  '?'  : 

/*  this  help  list 

*/ 

106 

cputs  (  CLS  ) ; 

/*  clear  the  display 

♦/ 

107 

center  (  "COMMAND  LIST  \n" 

); 

108 

center 

(  "1  =  select  port  1 

L  =  toggle  word  LENGTH  " 

i 

109 

center 

(  "2  =  select  port  2 

N  =  set  parity  to  NONE  " 

; 

110 

center 

(  "B  =  set  BAUD  rate 

0  =  set  parity  to  ODD  " 

; 

1 1 1 

center 

(  "E  =  set  parity  to  EVEN 

R  =  toggle  error  REPORTS" 

; 

112 

center 

(  "F  =  toggle  FLOW  control 

S  =  toggle  STOP  bits  " 

; 

113 

center 

(  "I  =  INITIALIZE  ints,  etc. 

Q  =  QUIT 

; 

114 

continue; 

115 

116 

case  *1'  : 

/*  toggle  word  length 

*/ 

117 

iobf  [  0  ]  "=  1; 

118 

iocwr  0  ; 

119 

break; 

120 

Figure  6-4.  Continued. 
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121 

case  'n'  : 

/* 

set  parity  off 

*/ 

122 

iobf  [  0  ]  &=~  (  m_PG  +  m_PE 

); 

123 

iocwr  ( ) ; 

124 

break; 

125 

126 

case  'o'  : 

/* 

set  parity  odd 

*/ 

127 

iobf  [  0  ]  1=  m_PG; 

128 

iobf  [  0  ]  &=~  in_PE; 

129 

iocwr  ( ) ; 

130 

break; 

131 

132 

case  'r'  : 

/* 

toggle  error  reports 

*/ 

133 

iobf  [  2  ]  1; 

134 

iocwr  0 ; 

135 

break; 

136 

137 

case  's'  : 

/* 

toggle  stop  bits 

*/ 

138 

iobf  [  0  ]  m_XS; 

139 

iocwr  ( ) ; 

140 

break; 

141 

142 

case  'q'  : 

143 

fclose  (  dvp  ) ; 

144 

exit  (  0  ) ; 

/* 

break  the  loop,  get  out 

♦/ 

145 

} 

146 

cputs  (  CLS  ) ; 

/* 

clear  the  display 

147 

center  {  "CURRENT  COMDVR 

STATUS" 

); 

148 

report  (  u,  dvp  ) ; 

/* 

report  current  status 

*/ 

149 

} 

150 

} 

151 

152 

center  (  s  )  char  ♦  s; 

/*  i 

centers  a  string  on  CRT 

*/ 

153 

{  int  i  ; 

154 

for  (  i  =  80  -  strlen  (  s  ) ; 

i  >  0;  ; 

i  -=  2  ) 

155 

putch  (  '  '  ) ; 

156 

cputs  (  s  ) ; 

157 

cputs  (  "\r\n"  ) ; 

158 

} 

159 

160 

iocwr  0 

/*  : 

lOCTL  Write  to  COMDVR 

*/ 

161 

{  rvs  .  X  .  ax  =  0x4403; 

162 

rvs  .  X  .  bx  =  fileno  (  dvp  ) 

; 

163 

rvs  .  X  .  cx  =  10; 

164 

rvs  .  X  .  dx  =  (  int  )  iobf; 

165 

intdos  (  &  rvs,  &  rvs  ) ; 

166 

} 

167 

168 

char  ♦  onoff  (  x  )  int  x  ; 

169 

{  return  (  x  ?  "  ON"  :  "  OFF"  ) 

; 

170 

} 

171 

Figure  6-4.  Continued. 
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172  :  report  (  unit  )  int  unit  ; 

173  :  {  char  temp  [  80  ]; 

174  :  rvs  .  x  .  ax  =  0x4402; 

175  :  rvs  .  x  .  bx  =  fileno  (  dvp  ); 

176  :  rvs  .  x  .  cx  =  10; 

177  :  rvs  .  x  .  dx  =  (  int  )  iobf; 

178  :  intdos  (  &  rvs,  &  rvs  );  /*  use  lOCTL  Read  to  get  data  */ 

179  :  sprintf  (  temp,  "\nDevice  ASY%d\t%d  BPS,  %d-c-%c\r\n\n", 

180  :  unit,  iobf  [  4  ],  /*  baud  rate  */ 

181  :  5  +  (  iobf  [  0  ]  &  m_WL  ),  /*  word  length  */ 

182  :  (  iobf  [  0  ]  &  m_PG  ? 

183  :  (  iobf  [  0  ]  &  m_PE  ?  'E'  :  'O'  )  :  'N'  ), 

184  :  (  iobf  [  0  ]  &  m_XS  ?  *2'  :  ’1'  ) ) ;  /*  stop  bits  */ 

185  :  cputs  (  temp  ); 

186  : 

187  :  cputs  (  "Hardware  Interrupts  are"  ); 

188  :  cputs  (  onoff  (  iobf  [  0  ]  &  HWINT  )); 

189  :  cputs  {  ",  Data  Terminal  Rdy"  ); 

1 90  :  cputs  (  onoff  (  iobf  [  0  ]  &  o_DTR  ) ) ; 

191  :  cputs  (  ",  Rqst  To  Send"  ); 

192  :  cputs  (  onoff  (  iobf  [  0  ]  &  o_RTS  )); 

193  :  cputs  (  ".\r\n"  ); 

194  : 

1 95  :  cputs  (  "Carrier  Detect"  ) ; 

1 96  :  cputs  (  onoff  (  iobf  [  1  ]  &  i— CD  ) ) ; 

197  :  cputs  (  ",  Data  Set  Rdy"  ); 

198  :  cputs  (  onoff  (  iobf  [  1  ]  &  i— DSR  )); 

199  :  cputs  (  ",  Clear  to  Send"  ); 

200  :  cputs  (  onoff  (  iobf  [  1  ]  &  i_CTS  ) ) ; 

201  :  cputs  (  ",  Ring  Indicator"  ); 

202  :  cputs  (  onoff  (  iobf  [  1  ]  &  i— RI  ) ) ; 

203  :  cputs  (  ".\r\n"  ); 

204  : 

205  :  cputs  (  1_SRE  &  iobf  [  1  ]  ?  "Xmtr  SR  Empty,  "  :  ""  ); 

206  :  cputs  (  1_HRE  &  iobf  [  1  ]  ?  "Xmtr  HR  Empty,  "  :  ""  ); 

207  :  cputs  (  1_BRK  &  iobf  [  1  ]  ?  "Break  Received,  "  :  ""  ); 

208  :  cputs  (  1_ER1  &  iobf  [  1  ]  ?  "Framing  Error,  "  :  ""  ); 

209  :  cputs  (  1_ER2  &  iobf  [  1  ]  ?  "Parity  Error,  "  :  ""  ); 

210  :  cputs  (  1_ER3  &  iobf  [  1  ]  ?  "Overrun  Error,  "  :  ""  ); 

211  :  cputs  (  1_RRF  &  iobf  [  1  ]  ?  "Rcvr  DR  Full,  "  :  ""  ); 

212  :  cputs  (  "\b\b.\r\n"  ); 

213  : 

214  :  cputs  (  "Reception  errors  "  ); 

215  ;  if  (  iobf  [  2  ]  ==  1  ) 

216  :  cputs  (  "are  encoded  as  graphics  in  buffer"  ); 

217  :  else 

218  :  cputs  (  "set  failure  flag"  ); 

219  :  cputs  (  ".\r\n"  ); 

220  : 

221  :  cputs  (  "Outgoing  Flow  Control  "  ) ; 

222  :  if  (  iobf  [  3  ]  &  4  ) 

Figure  6-4.  Continued.  (more) 
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223  ;  cputs  (  "by  XON  and  XOFF”  ) ; 

224  :  else 

225  :  if  (  iobf  [  3  ]  &  2  ) 

226  :  cputs  (  "by  RTS  and  CTS"  ); 

227  :  else 

228  :  if  {  iobf  [  3  ]  &  1  ) 

229  :  cputs  (  "by  DTR  and  DSR"  ) ; 

230  :  else 

231  :  cputs  (  "disabled"  ) ; 

232  :  cputs  (  ".\r\n"  ); 

233  :  } 

234  : 

235  :  /*end  of  cdvutl.c  */ 

Figure  6-4.  Continued. 


Although  CDVUTL  appears  complicated,  most  of  the  complexity  is  concentrated  in  the 
routines  that  map  driver  bit  settings  into  on-screen  display  text.  Each  such  mapping 
requires  several  lines  of  source  code  to  generate  only  a  few  words  of  the  display  report. 
Table  6-10  summarizes  the  functions  found  in  this  program. 


Table  6-10.  CDVUTL  Program  Functions. 


lines 

Name 

Description 

42-45 

mainO 

Conventional  entry  point. 

47-150 

disp() 

Main  dispatching  loop. 

152-158 

centerO 

Centers  text  on  CRT. 

160-166 

iocwrC) 

Writes  control  string  to  driver  with  lOCTL  Write. 

168-170 

onoffC) 

Returns  pointer  to  ON  or  OFF 

172-233 

reportO 

Reads  driver  status  and  reports  it  on  display. 

The  long  list  of  ^define  operations  at  the  start  of  the  listing  (lines  11  through  33)  helps 
make  the  bitmapping  comprehensible  by  assigning  a  symbolic  name  to  each  significant  bit 
in  the  four  UART  registers. 

The  mainO  procedure  of  CDVUTL  displays  a  banner  line  and  then  calls  the  dispatcher 
routine,  dispCX  to  start  operation.  CDVUTL  makes  no  use  of  either  command-line  parame¬ 
ters  or  the  environment,  so  the  usual  argument  declarations  are  omitted. 

Upon  entry  to  di^Q,  the  first  action  is  to  establish  the  default  driver  as  ASYl  by  setting 
M  =  i  and  opening  ASYl  (line  50);  the  program  then  enters  an  apparent  infinite  loop 
(lines  51  through  149). 

With  each  repetition,  the  loop  first  prompts  for  a  command  (line  52)  and  then  gets  the 
next  keystroke  and  uses  it  to  control  a  huge  switchQ  statement  (lines  53  through  145).  If 
no  case  matches  the  key  pressed,  the  switchQ  statement  does  nothing;  the  program  sim¬ 
ply  displays  a  report  of  all  current  conditions  at  the  selected  driver  (lines  146  through  148) 
and  then  closes  the  loop  back  to  issue  a  new  prompt  and  get  another  keystroke. 
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However,  if  the  key  pressed  matches  one  of  the  cases  in  the  switchQ  statement,  the  corre- 
spending  command  is  executed.  The  digits  1  (line  55)  and  2  (line  61)  select  the  driver  to 
be  affected.  The  ?  key  (line  105)  causes  the  list  of  valid  command  keys  to  be  displayed. 

The  q  key  (line  142)  causes  the  program  to  terminate  by  calling  exit(  0)  and  is  the  only 
exit  from  the  infinite  loop.  The  other  valid  keys  all  change  one  or  more  bits  in  the  lOCTL 
control  string  to  modify  corresponding  attributes  of  the  driver  and  then  send  the  string  to 
the  driver  by  using  the  MS-DOS  lOCTL  Write  function  (Interrupt  21H  Function  44H  Sub¬ 
function  03H)  via  function  ioewrQ  (lines  160  through  166). 

After  the  command  is  executed  (except  for  the  q  command,  which  terminates  operation 
of  CDVUTL  and  returns  to  MS-DOS  command  level,  and  the  ?  command,  which  displays 
the  command  list),  the  reportO  function  (lines  172  through  233)  is  called  (at  line  148)  to 
display  all  of  the  driver’s  attributes,  including  those  just  changed.  This  function  issues  an 
lOCTL  Read  command  (Interrupt  21H  Function  44H  Subfunction  02H,  in  lines  174  through 
178)  to  get  new  status  information  into  the  control  string  and  then  uses  a  sequence  of  bit 
filtering  (lines  179  through  232)  to  translate  the  obtained  status  information  into  words  for 
display. 

The  special  console  I/O  routines  provided  in  Microsoft  C  libraries  have  been  used  exten¬ 
sively  in  this  routine.  Other  compilers  may  require  changes  in  the  names  of  such  library 
routines  as  getch  or  dosint  as  well  as  in  the  names  of  ^include  files  (lines  6  through  9). 

Each  of  the  actual  command  sequences  changes  only  a  few  bits  in  one  of  the  10  bytes  of 
the  command  string  and  then  writes  the  string  to  the  driver.  A  full-featured  communica¬ 
tions  program  might  make  several  changes  at  one  time — for  example,  switching  from 
7-bit,  even  parity,  XON/XOFF  flow  control  to  8-bit,  no  parity,  without  flow  control  to  pre¬ 
vent  losing  any  bytes  with  values  of  IIH  or  13H  while  performing  a  binary  file  transfer  with 
error-correcting  protocol.  In  such  a  case,  the  program  could  make  all  required  changes  to 
the  control  string  before  issuing  a  single  lOCTL  Write  to  put  them  into  effect. 


The  Traditional  Approach 

Because  the  necessary  device  driver  has  never  been  a  part  of  MS-DOS,  most  communica¬ 
tions  programs  are  written  to  provide  and  install  their  own  port  driver  code  and  remove  it 
before  returning  to  MS-DOS.  The  second  sample  program  package  in  this  article  illustrates 
this  approach.  Although  the  major  part  of  the  package  is  written  in  Microsoft  C,  three 
assembly-language  modules  are  required  to  provide  the  hardware  interrupt  service  rou¬ 
tines,  the  exception  handler,  and  faster  video  display.  They  are  discussed  first. 

The  hardware  ISR  module 

The  first  module  is  a  handler  to  service  UART  interrupts.  Code  for  this  handler,  including 
routines  to  install  it  at  entry  and  remove  it  on  exit,  appears  in  CH1.ASM,  shown  in  Figure 
6-5. 
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TITLE  CHI .ASM 

;  CHI .ASM  —  support  file  for  CTERM.C  terminal  emulator 
;  set  up  to  work  with  COM2 

;  for  use  with  Microsoft  C  and  SMALL  model  only... 

—TEXT  segment  byte  public  'CODE' 

-TEXT  ends 

—DATA  segment  byte  pubj.ic  'DATA' 


10 

-DATA 

ends 

11 

CONST 

segment 

byte  public 

CONST ' 

12 

CONST 

ends 

13 

-BSS 

segment 

byte  public 

'BSS' 

14 

-BSS 

ends 

15 

16 

DGROUP 

GROUP 

CONST,  -BSS, 

-DATA 

17 

assume 

cs:-TEXT,  DS 

: DGROUP,  ES: DGROUP,  SS: DGROUP 

18 

19 

-TEXT 

segment 

20 

21 

public 

— i— m,  — rdmdm. 

_Send— Byte, — wrtmdm, — set— mdm, — u_m 

22 

23 

bport 

EQU 

02F8h 

;  COM2  base  address,  use  03F8H  for 

24 

getiv 

EQU 

350Bh 

;  COM2  vectors,  use  OCH  for  COM1 

25 

putiv 

EQU 

250Bh 

26 

imrmsk 

EQU 

00001000b 

;  COM2  mask,  use  000001 OOb  for  COM1 

27 

oiv— 0 

DW 

0 

;  old  int  vector  save  space 

28 

oiv— s 

DW 

0 

29 

30 

bf_pp 

DW 

in-bf 

;  put  pointer  (last  used) 

31 

bf_gp 

DW 

in_bf 

;  get  pointer  (next  to  use) 

32 

bf-bq 

DW 

in_bf 

;  start  of  buffer 

33 

bf-fi 

DW 

b— last 

;  end  of  buffer 

34 

35 

in— bf 

DB 

512  DUP  (?) 

;  input  buffer 

36 

37 

b-last 

EQU 

$ 

;  address  just  past  buffer  end 

38 

39 

bd-dv 

DW 

0417h 

;  baud  rate  divisors  (0=110  bps) 

40 

DW 

0300h 

;  code  1  =  150  bps 

41 

DW 

0180h 

;  code  2  =  300  bps 

42 

DW 

OOCOh 

;  code  3  =  600  bps 

43 

DW 

0060h 

;  code  4  =  1200  bps 

44 

DW 

0030h 

;  code  5  =  2400  bps 

45 

DW 

001  8h 

;  code  6  =  4800  bps 

46 

DW 

OOOCh 

;  code  7  =  9600  bps 

47 

48 

— set— mdm  proc 

near 

;  replaces  BIOS  'init'  function 

49 

PUSH 

BP 

50 

MOV 

BP,SP 

;  establish  stackframe  pointer 

51 

PUSH 

ES 

;  save  registers 

C0M1 


Figure  6-5.  CHI. ASM 
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52 

PUSH 

DS 

53 

MOV 

AX,CS 

54 

MOV 

DS,AX 

55 

MOV 

ES,AX 

56 

MOV 

AH, [BP+4] 

57 

MOV 

DX,BPORT+3 

58 

MOV 

AL,80h 

59 

OUT 

DX,AL 

60 

MOV 

DL,AH 

61 

MOV 

CL,  4 

62 

ROL 

DL,CL 

63 

AND 

DX, 00001110b 

64 

MOV 

D I, OFFSET  bd_dv 

65 

ADD 

DI,DX 

66 

MOV 

DX,BPORT+1 

67 

MOV 

AL, [DI+1 ] 

68 

OUT 

DX,  AL 

69 

MOV 

DX,BPORT 

70 

MOV 

AL, [DI] 

71 

OUT 

DX,AL 

72 

MOV 

AL,AH 

73 

AND 

AL, 00011111b 

74 

MOV 

DX,BPORT+3 

75 

OUT 

DX,AL 

76 

MOV 

DX,BPORT+2 

77 

MOV 

AL,  1 

78 

OUT 

DX,AL 

79 

POP 

DS 

80 

POP 

ES 

81 

MOV 

SP,BP 

82 

POP 

BP 

83 

RET 

84 

_set_mdm  endp 

85 

86 

_wrtmdm  proc 

near 

87  ; 

_Send— Byte : 

88 

PUSH 

BP 

89  : 

MOV 

BP,SP 

90 

PUSH 

ES 

91 

PUSH 

DS 

92 

MOV 

AX,CS 

93 

MOV 

DS,AX 

94 

MOV 

ES,AX 

95 

MOV 

DX,BPORT+4 

96 

MOV 

AL, OBh 

97 

OUT 

DX,AL 

98 

MOV 

DX,BPORT+6 

99 

MOV 

BH,30h 

100 

CALL 

w_tmr 

101 

JNZ 

w_out 

102 

MOV 

DX, BPORT+5 

;  point  them  to  CODE  segment 


;  get  parameter  passed  by  C 
;  point  to  Line  Control  Reg 
;  set  DLAB  bit  (see  text) 

;  shift  param  to  BAUD  field 


;  mask  out  all  other  bits 

;  make  pointer  to  true  divisor 
;  set  to  high  byte  first 

;  put  high  byte  into  UART 
;  then  to  low  byte 

;  now  use  rest  of  parameter 
;  to  set  Line  Control  Reg 


;  Interrupt  Enable  Register 
;  Receive  type  only 

;  restore  saved  registers 


;  write  char  to  modem 
;  name  used  by  main  program 

;  set  up  pointer  and  save  regs 


;  establish  DTR,  RTS,  and  0UT2 


;  check  for  on  line,  CTS 


;  timed  out 

;  check  for  UART  ready 


Figure  6-5.  Continued. 
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103 

MOV 

BH,20h 

104 

CALL 

w_tmr 

105 

JNZ 

w_out 

106 

MOV 

DX,BPORT 

107 

MOV 

AL, [BP+4] 

108 

OUT 

DX,AL 

109 

w_out : 

POP 

DS 

110 

POP 

ES 

111 

MOV 

SP,BP 

112 

POP 

BP 

113 

RET 

114 

—wrtmdm 

endp 

115 

116 

_rdmdm 

proc 

near 

117 

PUSH 

BP 

118 

MOV 

BP,SP 

119 

PUSH 

ES 

120 

PUSH 

DS 

121 

MOV 

AX,CS 

122 

MOV 

DS,AX 

123 

MOV 

ES,AX 

124 

MOV 

AX, OFFFFh 

125 

MOV 

BX,bf_gp 

126 

CMP 

BX, bf_pp 

127 

JZ 

nochr 

128 

INC 

BX 

129 

CMP 

BX,bf_fi 

130 

JNZ 

noend 

131 

MOV 

BX,bf_bg 

132 

noend: 

MOV 

AL, [BX] 

133 

MOV 

bf_gp,BX 

134 

INC 

AH 

135 

nochr : 

POP 

DS 

136 

POP 

ES 

137 

MOV 

SP,BP 

138 

POP 

BP 

139 

RET 

140 

—rdmdrn 

endp 

141 

142 

w_tmr 

proc 

near 

143 

MOV 

BL,  1 

144 

w_tm1  : 

SUB 

CX,CX 

145 

w_tm2 : 

IN 

AL,DX 

146 

MOV 

AH,AL 

147 

AND 

AL,BH 

148 

CMP 

AL,BH 

149 

JZ 

w_tm3 

150 

LOOP 

w_tm2 

151 

DEC 

BL 

152 

JNZ 

w_tm1 

153 

OR 

BH,BH 

;  timed  out 

;  send  out  to  UART  port 
;  get  char  passed  from  C 

;  restore  saved  regs 


;  reads  byte  from  buffer 
;  set  up  ptr,  save  regs 


;  set  for  EOF  flag 
;  use  "get"  ptr 
;  compare  to  "put" 

;  same,  empty 
;  else  char  available 
;  at  end  of  bfr? 

/  no 

;  yes,  set  to  beg 
;  get  the  char 
;  update  "get"  ptr 
;  zero  AH  as  flag 
;  restore  regs 


;  wait  timer,  double  loop 
;  set  up  inner  loop 
;  check  for  requested  response 
;  save  what  came  in 
;  mask  with  desired  bits 
;  then  compare 

;  got  it,  return  with  ZF  set 
;  else  keep  trying 
;  until  double  loop  expires 

;  timed  out,  return  NZ 


Figure  6-5.  Continued. 
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154 

w_tm3 : 

RET 

155 

w_tmr 

endp 

156 

157 

;  hardware  interrupt  service 

routine 

158 

rts_m: 

CLI 

159 

PUSH 

DS 

; 

save  all  regs 

160 

PUSH 

AX 

161 

PUSH 

BX 

162 

PUSH 

CX 

163 

PUSH 

DX 

164 

PUSH 

CS 

; 

set  DS  same  as  CS 

165 

POP 

DS 

166 

MOV 

DX,BPORT 

; 

grab  the  char  from  UART 

167 

IN 

AL,DX 

168 

MOV 

BX,bf_pp 

use  "put"  ptr 

169 

INC 

BX 

step  to  next  slot 

170 

CMP 

BX,bf_fi 

past  end  yet? 

171 

JNZ 

nofix 

no 

172 

MOV 

BX,bf_bg 

7 

yes,  set  to  begin 

173 

nofix : 

MOV 

[BX] ,AL 

7 

put  char  in  buffer 

174 

MOV 

bf_pp,BX 

7 

update  "put"  ptr 

175 

MOV 

AL,20h 

f 

send  EOI  to  8259  chip 

176 

OUT 

20h,AL 

177 

POP 

DX 

; 

restore  regs 

178 

POP 

CX 

179 

POP 

BX 

180 

POP 

AX 

181 

POP 

DS 

182 

I  RET 

183 

184 

_i_m 

proc 

near 

7 

install  modem  service 

185 

PUSH 

BP 

186 

MOV 

BP,  SP 

; 

save  all  regs  used 

187  : 

PUSH 

ES 

188 

PUSH 

DS 

189 

MOV 

AX,CS 

; 

set  DS,ES=CS 

190 

MOV 

DS,AX 

191 

MOV 

ES,AX 

192 

MOV 

DX,BPORT+l 

; 

Interrupt  Enable  Reg 

193 

MOV 

AL,0Fh 

; 

enable  all  ints  now 

194 

OUT 

DX,AL 

195 

196 

imi  : 

MOV 

DX,BPORT+2 

clear  junk  from  UART 

197 

IN 

AL,DX 

read  I ID  reg  of  UART 

198 

MOV 

AH,AL 

save  what  came  in 

199 

TEST 

AL,  1 

anything  pending? 

200 

JNZ 

im5 

no,  all  clear  now 

201 

CMP 

AH,  0 

yes.  Modem  Status? 

202 

JNZ 

im2 

no 

203 

MOV 

DX,BPORT+6 

yes,  read  MSR  to  clear 

204 

IN 

AL,DX 

Figure  6-5.  Continued. 
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205 

im2 : 

CMP 

AH,  2 

; 

Transmit  HR  empty? 

206 

JNZ 

im3 

no  (no  action  needed) 

207 

im3 : 

CMP 

AH,  4 

Received  Data  Ready? 

208 

JNZ 

im4 

no 

209 

MOV 

DX,BPORT 

yes,  read  it  to  clear 

210 

IN 

AL,DX 

21 1 

im4 : 

CMP 

AH,  6 

Line  Status? 

212 

JNZ 

imi 

no,  check  for  more 

213 

MOV 

DX,BPORT+5 

yes,  read  LSR  to  clear 

214 

IN 

AL,DX 

215 

JMP 

imi 

; 

then  check  for  more 

216 

217 

im5 : 

MOV 

DX,BPORT+4 

; 

set  up  working  conditions 

218 

MOV 

AL, OBh 

; 

DTR,  RTS,  OUT2  bits 

219 

OUT 

DX,  AL 

220 

MOV 

AL,  1 

; 

enable  RCV  interrupt  only 

221 

MOV 

DX,BPORT+1 

222 

OUT 

DX,AL 

223 

MOV 

AX,GETIV 

; 

get  old  int  vector 

224 

INT 

21h 

225 

MOV 

oiv_o, BX 

; 

save  for  restoring  later 

226 

MOV 

oiv_s, ES 

227 

MOV 

DX, OFFSET  rts_m 

; 

set  in  new  one 

228 

MOV 

AX,PUTIV 

229 

INT 

21h 

230 

IN 

AL,21h 

; 

now  enable  8259  PIC 

231 

AND 

AL,NOT  IMRMSK 

232 

OUT 

21h,AL 

233 

MOV 

AL,20h 

; 

then  send  out  an  EOI 

234 

OUT 

20h,AL 

235 

POP 

DS 

; 

restore  regs 

236 

POP 

ES 

237 

MOV 

SP,BP 

238 

POP 

BP 

239 

RET 

240 

_i_m 

endp 

241 

242 

_u_m 

proc 

near 

; 

uninstall  modem  service 

243 

PUSH 

BP 

244 

MOV 

BP,SP 

; 

save  registers 

245 

IN 

AL,21h 

/ 

disable  COM  int  in  8259 

246 

OR 

AL,  IMRMSK 

247 

OUT 

21h, AL 

248 

PUSH 

ES 

249 

PUSH 

DS 

250 

MOV 

AX,CS 

; 

set  same  as  CS 

251 

MOV 

DS,AX 

252 

MOV 

ES,AX 

253 

MOV 

AL,  0 

; 

disable  UART  ints 

254 

MOV 

DX,BPORT+1 

255 

OUT 

DX,AL 

Figure  6-5.  Continued. 
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256  :  MOV 

257  :  MOV 

258  :  MOV 

259  :  INT 

260  :  POP 

261  :  POP 

262  :  MOV 

263  :  POP 

264  :  RET 

265  :  _u_m  endp 

266  : 

267  :  _TEXT  ends 

268  ; 

269  :  END 

Figure  6-5.  Continued. 

The  routines  in  CHI  are  set  up  to  work  only  with  port  COM2;  to  use  them  with  COMl,  the 
three  symbolic  constants  BPORT  (base  address),  GETIV,  and  PUTIV  must  be  changed  to 
match  the  COMl  values.  Also,  as  presented,  this  code  is  for  use  with  the  Microsoft  C  small 
memory  model  only;  for  use  with  other  memory  models,  the  C  compiler  manuals  should 
be  consulted  for  making  the  necessary  changes.  See  also  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Structure  of  an  Application  Program. 

The  parts  of  CHI  are  listed  in  Table  6-11,  as  they  occur  in  the  listing.  The  leading  under¬ 
score  that  is  part  of  the  name  for  each  of  the  six  functions  is  supplied  by  the  C  compiler; 
within  the  C  program  that  calls  the  function,  the  underscore  is  omitted. 

Table  6-11.  CHI  Module  Functions. 


DX,oiv_o  ;  restore  original  vector 

DS, oiv_s 
AX, PUTIV 
21h 

DS  ;  restore  registers 

ES 

SP,BP 

BP 


lines 

Name 

Description 

1-26 

Administrative  details. 

27-46 

Data  areas. 

48-84 

_set^mdm 

Initializes  UART  as  specified  by  parameter  passed 
from  C. 

86-114 

_wrtmdm 

Outputs  character  to  UART. 

87 

JSend^Byte 

Entry  point  for  use  if  flow  control  is  added  to  system. 

116-140 

_rdmdm 

Gets  character  from  buffer  where  ISR  put  it,  or  signals 
that  no  character  available. 

142-155 

uUmr 

Wait  timer;  internal  routine  used  to  prevent  infinite 
wait  in  case  of  problems. 

157-182 

rts^m 

Hardware  ISR;  installed  by  and  removed  by 

184-240 

Installs  ISR,  saving  old  interrupt  vector. 

242-265 

_u^m 

Uninstalls  ISR,  restoring  saved  interrupt  vector. 
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For  simplest  operation,  the  ISR  used  in  this  example  (unlike  the  device  driver)  services 
only  the  received-data  interrupt;  the  other  three  types  of  IRQ  are  disabled  at  the  UART. 
Each  time  a  byte  is  received  by  the  UART,  the  ISR  puts  it  into  the  buffer.  Vcs&_rdmdm 
code,  when  called  by  the  C  program,  gets  a  byte  from  the  buffer  if  one  is  available.  If  not, 
_rdmdm  returns  the  C  EOF  code  (-1)  to  indicate  that  no  byte  can  be  obtained. 

To  send  a  byte,  the  C  program  can  call  oiihev  __.Send^Byte  ot_wrtmdm\  in  the  package 
as  shown,  these  are  alternative  names  for  the  same  routine.  In  the  more  complex  program 
from  which  this  package  was  adapted,  ^Send^Byte  is  called  when  flow  control  is  desired 
and  the  flow-control  routine  czWs  ^.wrtmdm.  To  implement  flow  control,  line  87  should  be 
deleted  from  CH1.ASM  and  a  control  function  named  Send_ByteO  should  be  added  to  the 
main  C  program.  Flow-control  tests  must  occur  in  Send^ByteQ;  ^wrtmdm  performs  the 
actual  port  interfacing. 

To  set  the  modem  baud  rate,  word  length,  and  parity,  ^set_mdm  is  called  from  the  C 
program,  with  a  setup  parameter  passed  as  an  argument.  The  format  of  this  parameter  is 
shown  in  Table  6-12  and  is  identical  to  the  IBM  BIOS  Interrupt  14H  Function  OOH 
(Initialization). 

Table  6-12.  set^mdmQ  Parameter  Coding. 


Binary 

Meaning 

OOOxxxxx 

Set  to  110  bps 

OOlxxxxx 

Set  to  150  bps 

OlOxxxxx 

Set  to  300  bps 

Ollxxxxx 

Set  to  600  bps 

lOOxxxxx 

Set  to  1200  bps 

lOlxxxxx 

Set  to  2400  bps 

llOxxxxx 

Set  to  4800  bps 

lllxxxxx 

Set  to  9600  bps 

xxxxOxxx 

No  parity 

xxxOlxxx 

ODD  Parity 

xxxllxxx 

EVEN  Parity 

xxxxxOxx 

1  stop  bit 

xxxxxlxx 

2  stop  bits  (1.5ifWL=5) 

xxxxxxOO 

Word  length  =  5 

xxxxxxOl 

Word  length  =  6 

xxxxxxlO 

Word  length  =  7 

xxxxxxll 

Word  length  =  8 

The  CHI  code  provides  a  512-byte  ring  buffer  for  incoming  data;  the  buffer  size  should  be 
adequate  for  reception  at  speeds  up  to  2400  bps  without  loss  of  data  during  scrolling. 
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The  exception-handler  module 

For  the  ISR  handler  of  CHI  to  be  usable,  an  exception  handler  is  needed  to  prevent  return 
of  control  to  MS-DOS  before  restores  the  ISR  vector  to  its  original  value.  If  a  pro¬ 

gram  using  this  code  returns  to  MS-DOS  without  calling  _w_m,  the  system  is  virtually  cer¬ 
tain  to  crash  when  line  noise  causes  a  received-data  interrupt  and  the  ISR  code  is  no  longer 
in  memory. 


A  replacement  exception  handler  (CH1A.ASM),  including  routines  for  installation,  access, 
and  removal,  is  shown  in  Figure  6-6.  Like  the  ISR,  this  module  is  designed  to  work  with 
Microsoft  C  (again,  the  small  memory  model  only). 

Note:  This  module  does  not  provide  for  fatal  disk  errors;  if  one  occurs,  immediate  restart¬ 
ing  is  necessary.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Customizing 
MS-DOS:  Exception  Handlers. 


TITLE  CH1A.ASM 

CH1A.ASM  —  support  file  for  CTERM.C  terminal  emulator 
this  set  of  routines  replaces  Ctrl-C/Ctrl-BREAK 
usage:  void  set_int(),  rst_int(); 

int  brokeO;  /*  boolean  if  BREAK  */ 
for  use  with  Microsoft  C  and  SMALL  model  only... 


9 

-TEXT 

segment 

10 

-TEXT 

ends 

11 

-DATA 

segment 

12 

-DATA 

ends 

13 

CONST 

segment 

14 

CONST 

ends 

15 

-BSS 

segment 

16 

-BSS 

ends 

17 

18 

DGROUP 

GROUP 

19 

ASSUME 

20 

21 

-DATA 

SEGMENT 

22 

23 

OLDINT1B  DD 

24 

25 

-DATA 

ENDS 

26 

27 

-TEXT 

SEGMENT 

28 

29 

PUBLIC 

30 

31 

my int 1b 

32 

mov 

33 

iret 

;  storage  for  original  INT  1BH  vector 


word  ptr  cs :brkflg, 1 Bh 


;  make  it  nonzero 


Figure  6-6.  CHIA.ASM. 
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34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 


word  ptr  cs :brkf Ig, 23h 


make  it  nonzero 


myint23 : 

mov 

iret 

brkflg  dw 

—broke  proc 
xor 
xchg 
ret 

—broke  endp 


_set— int  proc  near 

mov  ax,351bh  ;  get  interrupt  vector  for  IBH 

int  21 h  ;  (don't  need  to  save  for  23H) 

mov  word  ptr  oldint1b,bx  ;  save  offset  in  first  word 

mov  word  ptr  oldint1b+2/ es  ;  save  segment  in  second  word 


near 
ax,  ax 

ax, cs  rbrkflg 


flag  that  BREAK  occurred 

returns  0  if  no  break 
prepare  to  reset  flag 
return  current  flag  value 


push 

ds 

;  save  our  data  segment 

mov 

ax,  cs 

;  set  DS  to  CS  for  now 

mov 

ds,  ax 

lea 

dx,myint1b 

;  DS:DX  points  to  new  rout: 

mov 

ax, 251bh 

;  set  interrupt  vector 

int 

21h 

mov 

ax,  cs 

;  set  DS  to  CS  for  now 

mov 

ds,  ax 

lea 

dx, myint23 

;  DS:DX  points  to  new  rout: 

mov 

ax,2523h 

;  set  interrupt  vector 

int 

21h 

pop 

ds 

;  restore  data  segment 

ret 

:  endp 

:  proc 

near 

push 

ds 

;  save  our  data  segment 

Ids 

dx, oldintib 

;  DS:DX  points  to  original 

mov 

ax, 251bh 

;  set  interrupt  vector 

int 

21h 

pop 

ds 

;  restore  data  segment 

ret 

_rst— int  endp 


-TEXT 


ends 


Figure  6-6.  Continued. 


The  three  functions  in  CHIA  are  _set_int,  which  saves  the  old  vector  value  for  Interrupt 
IBH  (ROM  BIOS  Control-Break)  and  then  resets  both  that  vector  and  the  one  for  Interrupt 
23H  (Control-C  Handler  Address)  to  internal  ISR  code;  ^rst^int,  which  restores  the 
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original  value  for  the  Interrupt  IBH  vector;  and  which  returns  the  present  value  of 

an  internal  flag  (and  always  clears  the  flag,  just  in  case  it  had  been  set).  The  internal  flag  is 
set  to  a  nonzero  value  in  response  to  either  of  the  revectored  interrupts  and  is  tested  from 
the  main  C  program  via  the  stroke  function. 

The  video  display  module 

The  final  assembly-language  module  (CH2.ASM)  used  by  the  second  package  is  shown 
in  Figure  6-7.  This  module  provides  convenient  screen  clearing  and  cursor  positioning  via 
direct  calls  to  the  IBM  BIOS,  but  this  can  be  eliminated  with  minor  rewriting  of  the  rou¬ 
tines  that  call  its  functions.  In  the  original,  more  complex  program  (DT115.EXE,  available 
from  DL6  in  the  CLMFORUM  of  CompuServe)  from  which  CTERM  was  derived,  this  mod¬ 
ule  provided  windowing  capability  in  addition  to  improved  display  speed. 


1 

2 

TITLE 

CH2.ASM 

3 

;  CH2. 

ASM  —  support  file  for  CTERM. C  terminal  emulator 

4 

5 

for  use 

with  Microsoft  C  and  SMALL  model  only... 

6 

-TEXT 

segment 

byte  public 

•  CODE • 

7 

-TEXT 

ends 

8 

-DATA 

segment 

byte  public 

’  DATA ' 

9 

-DATA 

ends 

10 

CONST 

segment 

byte  public 

'  CONST ' 

1 1 

CONST 

ends 

12 

-BSS 

segment 

byte  public 

'BSS' 

13 

-BSS 

ends 

14 

15 

DGROUP 

GROUP 

CONST,  -BSS, 

-DATA 

16 

assume 

CS:-TEXT,  DS 

: DGROUP,  ES: DGROUP,  SS; DGROUP 

17 

18 

-TEXT 

segment 

19 

20 

public 

r  1 55 .  ml  or _ deol _ i__v _ kev _ wrehr _ \ 

21 

22 

atrib 

DB 

0 

;  attribute 

23 

— coir 

DB 

0 

;  color 

24 

V— bas 

DW 

0 

;  video  segment 

25 

V— ulc 

DW 

0 

;  upper  left  corner  cursor 

26 

V— Ire 

DW 

184Fh 

;  lower  right  corner  cursor 

27 

V— col 

DW 

0 

;  current  cbl/row 

28 

29 

_ key 

proc 

near 

;  get  keystroke 

30 

PUSH 

BP 

31 

MOV 

AH,  1 

;  check  status  via  BIOS 

32 

INT 

16h 

33 

MOV 

AX, OFFFFh 

34 

JZ 

keyOO 

;  none  ready,  return  EOF 

35 

MOV 

AH,  0 

;  have  one,  read  via  BIOS 

Figure  6-7.  CH2.ASM.  (more) 
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36 

INT 

16h 

37 

keyOO: 

POP 

BP 

38 

RET 

39 

_ key 

endp 

40 

41 

_ ^wrchr 

proc 

near 

42 

PUSH 

BP 

43 

MOV 

BP,SP 

44 

MOV 

AL, [BP+4]  ;  get  char  passed  by  C 

45 

CMP 

AL,  »  ' 

46 

JNB 

prchr  ;  printing  char,  go  do 

it 

47 

CMP 

AL,8 

48 

JNZ 

notbs 

49 

DEC 

BYTE  PTR  v_col  ;  process 

backspace 

50 

MOV 

AL,byte  ptr  v_col 

51 

CMP 

AL,byte  ptr  v_ulc 

52 

JB 

nxt_c  ;  step  to 

next  column 

53 

JMP 

norml 

54 

55 

notbs : 

CMP 

AL,  9 

56 

JNZ 

notht 

57 

MOV 

AL,byte  ptr  v_col  ; 

process  HTAB 

58 

ADD 

> 

CD 

59 

AND 

AL,0F8h 

60 

MOV 

byte  ptr  v_col,AL 

61 

CMP 

AL,byte  ptr  v_lrc 

62 

JA 

nxt_c 

63 

JMP 

SHORT  norml 

64 

65 

notht : 

CMP 

AL, OAh 

66 

JNZ 

not  If 

67 

MOV 

AL,byte  ptr  v__col+1  ; 

process  linefeed 

68 

INC 

AL 

69 

CMP 

AL,byte  ptr  v_lrc+1 

70 

JBE 

nohti 

71 

CALL 

scrol 

72 

MOV 

AL,byte  ptr  v_lrc+1 

73 

nohti : 

MOV 

byte  ptr  v_col+1,AL 

74 

JMP 

SHORT  norml 

75 

76 

not If : 

CMP 

AL,0Ch 

77 

JNZ 

ck_cr 

78 

CALL 

_ els  ;  process 

formfeed 

79 

JMP 

SHORT  ignor 

80 

81 

ck_cr : 

CMP 

AL,0Dh 

82 

JNZ 

ignor  ;  ignore  all  other  CTL 

chars 

83 

MOV 

AL,byte  ptr  v_ulc  ; 

process  CR 

84 

MOV 

byte  ptr  v_col,AL 

85 

JMP 

SHORT  norml 

86 

Figure  6-7.  Continued.  (more) 
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87 

prchr : 

MOV 

AH,_colr 

process  printing  char 

88 

PUSH 

AX 

89 

XOR 

AH,  AH 

90 

MOV 

AL,byte  ptr 

v_col+1 

91 

PUSH 

AX 

92 

MOV 

AL,byte  ptr 

v_col 

93 

PUSH 

AX 

94 

CALL 

wrtvr 

95 

MOV 

SP,BP 

96 

nxt_c : 

INC 

BYTE  PTR  v_col  ; 

advance  to  next  column 

97 

MOV 

AL,byte  ptr 

v_col 

98 

CMP 

AL,byte  ptr 

v_lrc 

99 

JLE 

norml 

100 

MOV 

AL,0Dh 

/ 

went  off  end,  do  CR/LF 

101 

PUSH 

AX 

102 

CALL 

_ wrchr 

103 

POP 

AX 

104 

MOV 

AL,  OAh 

105 

PUSH 

AX 

106 

CALL 

_ ^wrchr 

107 

POP 

AX 

108 

norml : 

CALL 

set_cur 

109 

ignor : 

MOV 

SP,BP 

110 

POP 

BP 

111 

RET 

112 

_ wrchr 

endp 

113 

114 

_ i_v 

proc 

near 

; 

establish  video  base  segment 

115 

PUSH 

BP 

116 

MOV 

BP,SP 

117 

MOV 

AX, OBOOOh 

; 

mono,  B800  for  CGA 

118 

MOV 

v_bas,  AX 

; 

could  be  made  automatic 

119 

MOV 

SP,BP 

120 

POP 

BP 

121 

RET 

122 

_ i_v 

endp 

123 

124 

_ ^wrpos 

proc 

near 

; 

set  cursor  position 

125 

PUSH 

BP 

126 

MOV 

BP,SP 

127 

MOV 

DH, [BP+4] 

row  from  C  program 

128 

MOV 

DL, [BP+6] 

col  from  C  program 

129 

MOV 

v_col, DX 

cursor  position 

130 

MOV 

BH, atrib 

attribute 

131 

MOV 

AH,  2 

132 

PUSH 

BP 

133 

INT 

lOh 

134 

POP 

BP 

135 

MOV 

AX, v_col 

; 

return  cursor  position 

136 

MOV 

SP,BP 

137 

POP 

BP 

Figure  6-7.  Continued. 
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138 

RET 

139 

_ wrpos  endp 

140 

141 

set_cur  proc 

near 

; 

set  cursor  to  v_col 

142 

PUSH 

BP 

143 

MOV 

BP,SP 

144 

MOV 

DX, v_col 

; 

use  where  v_col  says 

145 

MOV 

BH, atrib 

146 

MOV 

AH,  2 

147 

PUSH 

BP 

1  48 

INT 

lOh 

149 

POP 

BP 

150 

MOV 

AX, v_col 

151 

MOV 

SP,BP 

152 

POP 

BP 

153 

RET 

154 

set_cur  endp 

155 

156 

_ color  proc 

near 

; 

—Color (fg,  bg) 

157 

PUSH 

BP 

158 

MOV 

BP,SP 

159 

MOV 

AH, [BP+6] 

; 

background  from  C 

160 

MOV 

AL, [BP+4] 

; 

foreground  from  C 

161 

MOV 

CX,4 

162 

SHL 

AH,  CL 

163 

AND 

AL, OFh 

164 

OR 

AL,AH 

; 

pack  up  into  1  byte 

165 

MOV 

_colr, AL 

; 

store  for  handler's  use 

166 

XOR 

AH,  AH 

167 

MOV 

SP,BP 

168 

POP 

BP 

169 

RET 

170 

_ color  endp 

171 

172 

scrol  proc 

near 

; 

scroll  CRT  up  by  one  line 

173 

PUSH 

BP 

174 

MOV 

BP,  SP 

175 

MOV 

AL,  1 

; 

count  of  lines  to  scroll 

176 

MOV 

CX, v_ulc 

177 

MOV 

DX, v_lrc 

178 

MOV 

BH,_colr 

179 

MOV 

AH,  6 

180 

PUSH 

BP 

181 

INT 

lOh 

; 

use  BIOS 

1  82 

POP 

BP 

183 

MOV 

SP,BP 

184 

POP 

BP 

1  85 

RET 

186 

scrol  endp 

187 

188 

_ els  proc 

near 

; 

clear  CRT 

Figure  6-7.  Continued.  (more) 
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189 

PUSH 

BP 

190 

MOV 

BP,SP 

191 

MOV 

AL,  0 

; 

flags  CLS  to  BIOS 

192 

MOV 

CX, v_ulc 

193 

MOV 

v_col , CX 

; 

set  to  HOME 

194 

MOV 

DX, v_lrc 

195 

MOV 

BH,_colr 

196 

MOV 

AH,  6 

1  97 

PUSH 

BP 

198 

I  NT 

lOh 

; 

use  BIOS  scroll  up 

199 

POP 

BP 

200 

CALL 

set_cur 

; 

cursor  to  HOME 

201 

MOV 

SP,BP 

202 

POP 

BP 

203 

RET 

204 

_ els 

endp 

205 

206 

_ deol 

proc 

near 

; 

delete  to  end  of  line 

207 

PUSH 

BP 

208 

MOV 

BP,SP 

209 

MOV 

AL,  •  ' 

210 

MOV 

AH,_colr 

; 

set  up  blanks 

211 

PUSH 

AX 

212 

MOV 

AL,byte  ptr 

v_col+1 

213 

XOR 

AH,  AH 

; 

set  up  row  value 

214 

PUSH 

AX 

215 

MOV 

AL,byte  ptr 

v_col 

216 

217 

deoil : 

CMP 

AL,byte  ptr 

v_lrc 

218 

JA 

deol2 

/ 

at  RH  edge 

219 

PUSH 

AX 

/ 

current  location 

220 

CALL 

wrtvr 

r 

write  a  blank 

221 

POP 

AX 

222 

INC 

AL 

; 

next  column 

223 

JMP 

deoil 

; 

do  it  again 

224 

225 

deol2: 

MOV 

AX, v_col 

; 

return  cursor  position 

226 

MOV 

SP,BP 

227 

POP 

BP 

228 

RET 

229 

_ deol 

endp 

230 

231 

wrtvr 

proc 

near 

; 

write  video  RAM  (col. 

232 

PUSH 

BP 

233 

MOV 

BP,SP 

set  up  arg  ptr 

234 

MOV 

DL, [BP+4] 

column 

235 

MOV 

DH, [BP+6] 

row 

236 

MOV 

BX, [BP+8] 

char/ atr 

237 

MOV 

AL,  80 

calc  offset 

238 

MUL 

DH 

239 

XOR 

DH,DH 

char/atr) 


Figure  6-7.  Continued. 
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240 

ADD 

AX,DX 

241 

ADD 

AX,  AX 

;  adjust  bytes  to  words 

242 

PUSH 

ES 

;  save  seg  reg 

243 

MOV 

DI,AX 

244 

MOV 

AX, V— bas 

;  set  up  segment 

245 

MOV 

ES,AX 

246 

MOV 

AX,BX 

;  get  the  data 

247 

STOSW 

;  put  on  screen 

248 

POP 

ES 

;  restore  regs 

249 

MOV  ■ 

SP,BP 

250 

POP 

BP 

251 

RET 

252 

wrtvr 

endp 

253 

254 

-TEXT 

ends 

255 

256 

END 

Figure  6-7.  Continued. 


The  sample  smarter  terminal  emulator:  CTERM.C 

Given  the  interrupt  handler  (CHI),  exception  handler  (CHIA),  and  video  handler  (CH2),  a 
simple  terminal  emulation  program  (CTERM.C)  can  be  presented.  The  major  functions  of 
the  program  are  written  in  Microsoft  C;  the  listing  is  shown  in  Figure  6-8. 


1 

/*  Terminal  Emulator 

(cterm.c) 

2 

*  Jim  Kyle,  1987 

3 

♦ 

4 

*  Uses  files  CHI, 

CHIA, 

and 

CH2  for  MASM  support . . . 

5 

6 

*/ 

7 

#include  <stdio.h> 

8 

#include  <conio.h> 

/* 

Special  console  i/o 

*/ 

9 

#include  <stdlib.h> 

/* 

misc  definitions 

*/ 

10 

#include  <dos.h> 

/* 

defines  intdos () 

*/ 

1 1 

#include  <string.h> 

12 

#define  BRK 

/♦ 

control  characters 

*/ 

13 

#define  ESC  '  [  ' 

14 

#define  XON 

15 

#define  XOFF  'S'-'@' 

16 

17 

#define  True  1 

18 

#define  False  0 

19 

20 

#define  Is_Function— Key (C)  ( 

(C)  = 

==  ESC  ) 

21 

22 

static  char  capbfr  [  4096  ] ; 

/* 

capture  buffer 

*/ 

23 

static  int  wh. 

24 

ws; 

Figure  6-8.  CTERM.C. 

(more) 
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26 

static  int  I, 

27 

waitchr  =  0, 

28 

vflag  =  False, 

29 

capbp. 

30 

capbc. 

31 

Ch, 

32 

Want_7_Bit  =  True, 

33 

ESC_Seq_State  =0; 

/*  escape  sequence  state  variable 

*/ 

34 

35 

int  _cx  , 

36 

-cy. 

37 

_atr  =  0x07, 

/*  white  on  black 

*/ 

38 

_pag  =  0, 

39 

oldtop  =  0, 

40 

oldbot  =  0x1 84f; 

41 

42 

FILE  *  in_file  =  NULL; 

/*  start  with  keyboard  input 

*/ 

43 

FILE  *  cap_file  =  NULL; 

44 

45 

#include  "cterm.h" 

/*  external  declarations,  etc. 

*/ 

46 

47 

int  Wants_To_Abort  () 

/*  checks  for  interrupt  of 

script 

*/ 

48 

{  return  broke  (); 

49 

} 

50 

void 

51 

52 

main  (  argc,  argv  )  int  . 

argc  ; 

/*  main  routine 

*/ 

53 

char  *  argv  [ ] ; 

54 

{  char  *  cp. 

55 

*  addext  { ) ; 

56 

if  {  argc  >  1  ) 

/*  check  for  script  filename 

*/ 

57 

:  in_file  =  fopen  (  addext  ( 

argv  [  1  ],  ".SCR"  ),  "r"  ) 

)  ; 

58 

:  if  {  argc  >  2  ) 

/*  check  for  capture  filename 

*/ 

59 

:  cap_file  =  fopen  (  addext 

(  argv  [  2  ],  ".CAP"  ),  "w" 

)•; 

60 

set_int  ( ) ; 

/*  install  CHI  module 

*/ 

61 

Set_Vid  ( ) ; 

/*  get  video  setup 

*/ 

62 

els  0; 

/*  clear  the  screen 

*/ 

63 

:  eputs  (  "Terminal  Emulator" 

);  /*  tell  who's  working 

*/ 

64 

eputs  (  "\r\n<  ESC  for 

local 

commands  >\r\n\n"  ) ; 

65 

Want_7_Bit  =  True; 

66 

ESC_Seq_State  =  0; 

67 

Init—Comm  (); 

/*  set  up  drivers,  etc. 

*/ 

68 

while  (  1  ) 

/*  main  loop 

*/ 

69 

{  if  ( {  Ch  =  kb_file 

0)  > 

0  )  /*  check  local 

*/ 

70 

:  {  if  (  Is_Function_Key 

(  Ch  )) 

71 

{if  (  docmd 

0  < 

0  )  /*  command 

*/ 

72 

break; 

73 

} 

74 

else 

75 

Send_Byte  (  ' 

Ch  &  0x7F  );  /*  else  send  it 

*/ 

Figure  6-8.  Continued. 


(more) 


Section  11:  Programming  in  the  MS-DOS  Environment  23 1 


Part  B:  Programming  for  MS-DOS 


76 

} 

77 

if  ( {  Ch  =  Read-Modem  ())  >=  0  ) 

/* 

check  remote 

*/ 

78 

{if  (  Want_7_Bit  ) 

79 

Ch  &=  0x7F; 

/* 

trim  off  high  bit 

*/ 

80 

switch  (  ESC_Seq_State  ) 

/* 

state  machine 

*/ 

81 

{ 

82 

case  0  : 

/* 

no  Esc  sequence 

*/ 

83 

switch  (  Ch  ) 

84 

{ 

85 

case  ESC  : 

/* 

Esc  char  received 

*/ 

86 

ESC_Seq_State  =  1  ; 

87 

break; 

88 

89 

default  : 

90 

if  (  Ch  ==  waitchr  ) 

/* 

wait  if  required 

*/ 

91 

waitchr  =  0; 

92 

if  (  Ch  ==  12  ) 

/* 

clear  screen  on  FF 

*/ 

93 

els  0; 

94 

else 

95 

if  (  Ch  !=  127  ) 

/* 

ignore  rubouts 

*/ 

96 

{  putchx  (  (char) 

Ch 

);  /*  handle  all  others 

*/ 

97 

put_cap  (  (char)  Ch  ) ; 

98 

) 

99 

} 

100 

break; 

101 

102 

case  1  :  /*  ESC  —  process 

any 

escape  sequences  here 

*/ 

103 

switch  (  Ch  ) 

104 

{ 

105 

case  ’A'  : 

/* 

VT52  up 

*/ 

106 

; 

/* 

nothing  but  stubs  here 

*/ 

107 

ESC_Seq_State  =  0; 

108 

break; 

109 

110 

case  'B*  : 

/* 

VT52  down 

*/ 

111 

; 

112 

ESC_Seq_State  =0; 

113 

break; 

114 

115 

case  'C  : 

/* 

VT52  left 

*/ 

116 

; 

117 

ESC_Seq_State  =  0; 

118 

break; 

119 

120 

case  'D'  : 

/* 

VT52  right 

*/ 

121 

; 

122 

ESC_Seq_State  =  0; 

123 

break; 

124 

125 

case  'E'  : 

/* 

VT52  Erase  CRT 

*/ 

126 

els  0; 

/* 

actually  do  this  one 

*/ 

Figure  6-8.  Continued. 
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127 

ESC_Seq_State  =  0; 

128 

break; 

129 

130 

case  *H'  : 

/* 

VT52  home  cursor 

*/ 

131 

locate  (0,  0  ) ; 

132 

ESC_Seq_State  =0; 

133 

break; 

134 

135 

case  ' j  *  : 

/* 

VT52  Erase  to  EOS 

*/ 

136 

deos  ( ) ; 

137 

ESC_Seq_State  =  0; 

138 

break; 

139 

140 

case  * [ •  :  /*  ANSI 

.SYS  -  VT100  sequence 

*/ 

141 

ESC_Seq_State  =  2; 

142 

break; 

143 

144 

default  : 

145 

putchx  (  ESC  ) ; 

/* 

pass  thru  all  others 

*/ 

146 

putchx  (  (char)  Ch  ) ; 

147 

ESC_Seq_State  =0; 

148 

} 

149 

break; 

150 

151 

case  2  : 

/* 

ANSI  3.64  decoder 

*/ 

152 

ESC_Seq_State  =0; 

/* 

not  implemented 

*/ 

153 

} 

154 

} 

155 

if  (  broke  ( ) ) 

/* 

check  CHI A  handlers 

*/ 

156 

{  cputs  {  "\r\n***BREAK***\r\n” 

); 

157 

break; 

158 

} 

159 

} 

/* 

end  of  main  loop 

*/ 

160 

if  (  cap_file  ) 

/* 

save  any  capture 

*/ 

161 

cap_flush  (); 

162 

Teriri—Comm  ( ) ; 

/* 

restore  when  done 

*/ 

163 

rst_int  ( ) ; 

/* 

restore  break  handlers 

*/ 

164 

exit  (  0  )  ; 

/* 

be  nice  to  MS-DOS 

*/ 

165 

} 

166 

167 

docmd  ( ) 

/* 

local  command  shell 

*/ 

168 

{  FILE  *  getfil  0; 

169 

int  wp; 

170 

wp  =  True; 

171 

if  (  !  in_file  ! 1  vflag  ) 

172 

cputs  (  ”\r\n\tCommand:  ”  ) ; 

/* 

ask  for  command 

*/ 

173 

else 

174 

wp  =  False; 

175 

Ch  =  toupper  (  kbd_wait  ()); 

/* 

get  response 

*/ 

176 

if  (  wp  ) 

177 

putchx  {  (char)  Ch  )  ; 

Figure  6-8.  Continued.  (more) 
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switch  (  Ch  )  /*  and  act  on  it 

{ 

case  'S'  : 
if  (  wp  ) 

cputs  (  "low  speed\r\n"  ) ; 

Set_Baud  (  300  ) ; 
break; 

case  'D'  : 
if  (  wp  ) 

cputs  (  "elay  (1-9  sec):  "  ); 

Ch  =  kbcL-wait  ( )  ; 
if  (  wp  ) 

putchx  (  (char)  Ch  ) ; 

Delay  (  1 000  *  (  Ch  -  ' 0 '  ) ) ; 
if  (  wp  ) 

putchx  (  ' \n '  ) ; 
break; 

case  'E'  ; 
if  (  wp  ) 

cputs  (  "ven  Parity\r\n"  ) ; 

Set-Parity  (  2  ) ; 
break; 

case  'F'  : 
if  (  wp  ) 

cputs  (  "ast  speed\r\n"  ) ; 

Set_Baud  (  1200  ); 
break; 

case  'H'  : 
if  (  wp  ) 

{  cputs  (  "\r\n\tVALID  COMMANDS : \r\n"  ); 
cputs  (  "\tD  =  delay  0-9  seconds . \r\n"  ); 
cputs  (  "\tE  =  even  parity. \r\n"  ); 
cputs  (  "\tF  =  (fast)  1 200-baud. \r\n"  ); 
cputs  (  "\tN  =  no  parity. \r\n"  ); 
cputs  (  "\tO  =  odd  parity. \r\n"  ); 
cputs  (  "\tQ  =  quit,  return  to  DOS.\r\n"  ); 
cputs  (  "\tR  =  reset  modem. \r\n''  ); 
cputs  (  "\tS  =  (slow)  300-baud. \r\n"  ); 
cputs  (  "\tU  =  use  script  file.\r\n"  ); 
cputs  (  "\tV  =  verify  file  input. \r\n"  ); 
cputs  (  "\tW  =  wait  for  char."  ); 

} 

break; 

case  'N'  : 
if  (  wp  ) 


Figure  6-8.  Continued. 
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cputs  (  ”o  Parity\r\n''  )  ; 

Set-Parity  (  1  ) ; 
break; 

case  'O'  : 
if  (  wp  ) 

cputs  (  "dd  Parity\r\n"  ) ; 

Set-Parity  (  3  )  ; 
break; 

case  'R'  : 
if  (  wp  ) 

cputs  (  "ESET  Comm  Port\r\n"  ) ; 

Init— Comm  ( ) ; 
break; 

case  'Q'  : 
if  (  wp  ) 

cputs  (  "  =  QUIT  Command\r\n"  ) ; 

Ch  =  (  -  1  In¬ 
break; 

case  'U'  : 

if  (  in— file  &&  !  vflag  ) 
putchx  (  ' U '  ) ; 
cputs  (  "se  file:  "  ); 
getfil  0 ; 
cputs  (  "File  "  ) ; 

cputs  (  in— file  ?  "Open\r\n"  :  "Bad\r\n"  ) ; 

waitchr  =0; 

break; 

case  'V  ; 
if  (  wp  ) 

{  cputs  (  "erify  flag  toggled  "  ) ; 

cputs  (  vflag  ?  "OFF\r\n"  :  "ON\r\n"  ) ; 

} 

vflag  =  vflag  ?  False  :  True; 
break; 

case  'W  : 
if  (  wp  ) 

cputs  (  "ait  for:  <"  ); 
waitchr  =  kbd— wait  (); 
if  (  waitchr  ==  ’  '  ) 

waitchr  =  0; 
if  (  wp  ) 

{if  (  waitchr  ) 

putchx  (  (char)  waitchr  ) ; 
else 

cputs  (  "no  wait"  ) ; 


Figure  6-8.  Continued. 
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279 

cputs  (  ”>\r\n"  ) ; 

280 

} 

281 

break; 

282 

283 

default  ; 

284 

if  (  wp  ) 

285 

{  cputs  (  "Don't  know  "  ); 

286 

putchx  {  (char)  Ch  ) ; 

287 

cputs  (  "\r\nUse  'H*  command 

for 

Help.\r\n"  ); 

288 

} 

289 

Ch  = 

290 

} 

291 

if  (  wp  ) 

/* 

if  window  open... 

*/ 

292 

{  cputs  (  "\r\n[any  key] \r"  ); 

293 

while  (  Read-Keyboard  ()  ==  EOF  ) 

/* 

wait  for  response 

*/ 

294 

; 

295 

} 

296 

return  Ch  ; 

297 

} 

298 

299 

kbd— wait  () 

/* 

wait  for  input 

Hc/ 

300 

{  int  c  ; 

301 

while  ((  c  =  kb_file  ())  ==  (  -  1  )) 

302 

; 

303 

return  c  &  255; 

304 

} 

305 

306 

kb_file  0 

/* 

input  from  kb  or  file 

*/ 

307 

{  int  c  ; 

308 

if  (  in_file  ) 

/* 

USING  SCRIPT 

*/ 

309 

{  c  =  Wants—To—Abort  (); 

/* 

use  first  as  flag 

*/ 

310 

if  (  waitchr  &&  !  c  ) 

31 1 

c  =  (  -  1  ); 

/* 

then  for  char 

♦/ 

312 

else 

313 

if  (  c  I !  (  c  =  getc  (  in_file 

))  = 

==  EOF  1  j  c  ==  26  ) 

314 

{  fclose  (  in_file  ) ; 

315 

cputs  (  "\r\nScript  File  Closed\r\n"  ) ; 

316 

in_file  =  NULL; 

317 

waitchr  =  0; 

318 

c  =  (  -  1  ); 

319 

} 

320 

else 

321 

if  (  c  ==  '\n'  ) 

/* 

ignore  LFs  in  file 

*/ 

322 

c  =  (  -  1  ); 

323 

if  (  c  ==  'W  ) 

/* 

process  Esc  sequence 

*/ 

324 

c  =  esc  ( ) ; 

325 

if  (  vflag  &&  c  !=  (  -  1  )) 

/* 

verify  file  char 

*/ 

326 

{  putchx  (  ' { '  ) ; 

327 

putchx  (  (char)  c  ) ; 

328 

putchx  (  ' }  '  ) ; 

329 

} 

Figure  6~8.  Continued. 
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} 

else 

c  =  Read-Keyboard  ( ) ; 
return  (  c  ) ; 


/*  USING  CONSOLE 
/*  if  not  using  file 


/*  script  translator 
/*  control  chars  in  file 


case  'N'  : 
c  =  ’\n'; 
break; 

case  'R'  : 
c  =  *\r'; 
break; 

case  'T'  : 
c  =  ' \t '  ; 
break; 

case  : 

c  =  getc  (  in_file  )  &  31 ; 
break; 

} 

return  (  c  ) ; 

} 


esc  ( ) 

{  int  c  ; 

c  =  getc  (  in_file  ) ; 
switch  (  toupper  (  c  ) ) 
{ 

case  *E'  : 
c  =  ESC; 
break; 


FILE  *  getfil  0 
{  char  fnm  [  20  ]  ; 

getnam  (  fnm,  15  );  /*  get  the  name 

if  (  !  (  strchr  (  fnm,  ' . '  ) ) ) 

strcat  (  fnm,  ”.SCR"  ); 
return  (  in_file  =  fopen  (  fnm,  ”r”  ) ) ; 


void  getnam  (  b,  s  )  char  *  b;  /*  take  input  to  buffer 

int  s  ; 

{  while  (  s  —  >  0  ) 

{  if  ({  *  b  =  (char)  kbd_wait  ())  !=  'Xr'  ) 

putchx  (  *  b  ++  ) ; 
else 

break  ; 

} 

putchx  (  '\n'  ); 


*/ 

*/ 


*/ 

*/ 


*/ 


*/ 


Figure  6-8.  Continued. 
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381 

*  b  =  0; 

382 

} 

383 

384 

char  *  addext  {  b. 

/* 

add  default  EXTension 

*/ 

385 

e  )  char  *  b. 

386 

*  e; 

387 

{  static  char  bfr  [  20  ]; 

388 

if  (  strchr  (  b,  ' . '  ) ) 

389 

return  (  b  ) ; 

390 

strcpy  (  bfr,  b  ) ; 

391 

strcat  (  bfr,  e  ) ; 

392 

return  (  bfr  ) ; 

393 

} 

394 

395 

void  put_cap  (  c  )  char  c  ; 

396 

{  if  (  cap_file  &&  c  !=  13  ) 

/* 

strip  out  CRs 

*/ 

397 

fputc  (  c,  cap_file  ) ; 

/* 

use  MS-DOS  buffering 

*/ 

398 

} 

399 

400 

void  cap-flush  () 

/* 

end  Capture  mode 

*/ 

401 

{  if  (  cap-file  ) 

402 

{  fclose  (  cap— file  ) ; 

403 

cap-file  =  NULL; 

404 

cputs  (  ''\r\nCapture  file  closed\r\n' 

); 

405 

} 

406 

} 

407 

408 

/*  TIMER  SUPPORT  STUFF 

(IBMPC/MSDOS) 

♦/ 

409 

static  long  timr; 

/* 

timeout  register 

*/ 

410 

411 

static  union  REGS  rgv  ; 

412 

413 

long  getmr  {) 

414 

{  long  now  ; 

/* 

msec  since  midnite 

*/ 

415 

rgv. X. ax  =  0x2c00; 

416 

intdos  (  &  rgv,  &  rgv  )  ; 

417 

now  =  rgv.h.ch; 

/* 

hours 

*/ 

418 

now  *=  60L; 

/* 

to  minutes 

♦/ 

419 

now  +=  rgv. h. cl; 

/* 

plus  min 

*/ 

420 

now  *=  60L; 

/* 

to  seconds 

*/ 

421 

now  +=  rgv.h.dh; 

/* 

plus  sec 

*/ 

422 

now  *=  100L; 

/* 

to  1/100 

*/ 

423 

now  +=  rgv.h.dl; 

/* 

plus  1/100 

*/ 

424 

return  (  1 OL  *  now  ) ; 

/* 

msec  value 

*/ 

425 

} 

426 

427 

void  Delay  (  n  )  int  n  ; 

/* 

sleep  for  n  msec 

*/ 

428 

{  long  wakeup  ; 

429 

wakeup  =  getmr  {)  +  (  long 

)  n;  /* 

wakeup  time 

*/ 

430 

while  (  getmr  ()  <  wakeup 

) 

431 

; 

/* 

now  sleep 

*/ 

Figure  6-8.  Continued. 
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432 

} 

433 

434 

void  Start-Timer  (  n  )  int 

n  ; 

/* 

set  timeout  for  n  sec 

435 

{  timr  =  getmr  ()  +  (  long 

)  n  *  1000L 

; 

436 

} 

437 

438 

Timer-Expired  ()  /* 

if  timeout 

return  1  else  return  0 

439 

{  return  (  getmr  ()  >  timr 

); 

440 

} 

441 

442 

Set— Vid  ( ) 

443 

{  -i-v  {); 

/* 

initialize  video 

444 

return  0; 

445 

} 

446 

447 

void  locate  {  row,  col  )  int  row  , 

448 

col; 

449 

{  — cy  =  row  %  25; 

450 

-cx  =  col  %  80; 

451 

— wrpos  (  row,  col  ) ; 

/* 

use  ML  from  CH2.ASM 

452 

} 

453 

454 

void  deol  () 

455 

{  —deol  ( )  ; 

/* 

use  ML  from  CH2.ASM 

456 

} 

457 

458 

void  deos  () 

459 

{  deol  0; 

460 

if  (  — cy  <  24  ) 

/* 

if  not  last,  clear 

461 

{  rgv.x.ax  =  0x0600; 

462 

rgv.x.bx  =  (  _ atr  « 

8  ); 

463 

rgv.x.cx  =  (  — cy  +  1 

)  «  8; 

464 

rgv.x.dx  =  0x1 84F; 

465 

int86  (  0x10,  &  rgv. 

&  rgv  ) ; 

466 

} 

467 

locate  (  _cy,  — cx  ) ; 

468 

} 

469 

470 

void  els  0 

471 

{  -els  0; 

/* 

use  ML 

472 

} 

473 

474 

void  cursor  (  yn  )  int  yn  ; 

475 

{  rgv.x.cx  =  yn  ?  0x0607  : 

0x2607; 

/* 

ON /OFF 

476 

rgv.x.ax  =  0x0100; 

477 

int86  (  0x10,  &  rgv,  &  rgv  ); 

478 

} 

479 

480 

void  revvid  (  yn  )  int  yn  ; 

481 

{if  (  yn  ) 

482 

—atr  =  —color  (  8,  7  ) ; 

/* 

black  on  white 

Figure  6-8.  Continued. 
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*/ 


*/ 


*/ 


*/ 


*/ 


*/ 


*/ 


♦/ 
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483  :  else 

484  :  _atr  =  _color  (  15,  0  );  /*  white  on  black  ♦/ 

485  :  } 

486  : 

487  :  putchx  (  c  )  char  c  ;  /*  put  char  to  CRT  */ 

488  :  {  if  (  c  ==  '\n'  ) 

489  :  putch  (  '\r'  ); 

490  :  putch  (  c  )  ; 

491  :  return  c  ; 

492  :  } 

493  : 

494  :  Read-Keyboard  () 

495  : 

496  :  {  int  c  ; 

497  :  if  {  kbhit  ()) 

498  :  return  (  getch  ()); 

499  :  return  (  EOF  ); 

500  ;  } 

501  : 

502  :  /*  MODEM  SUPPORT  */ 

503  :  static  char  mparm, 

504  :  wrk  [  80  ]  ; 

505  : 

506  :  void  Init-Comm  () 

507  :  {  static  int  ft  =  0; 

508  :  if  (  ft  ++  ==  0  ) 

509  :  i_m  ( ) ; 

510  :  Set-Parity  (  1  ); 

511  :  Set-Baud  (  1200  ); 

512  :  } 

513  : 

514  :  #define  B1200  0x80 

515  :  #define  B300  0x40 

516  : 

517  :  Set-Baud  (  n  )  int  n 

518  :  {  if  (  n  ==  300  ) 

519  :  mparm  =  (  mparm  &  0x1 F  )  +  B300; 

520  :  else 

521  :  if  (  n  ==  1200  ) 

522  :  mparm  =  (  mparm  &  0x1 F  )  +  B1200; 

523  :  else 

524  :  return  0;  /*  invalid  speed  */ 

525  :  sprintf  (  wrk,  "Baud  rate  =  %d\r\n",  n  ); 

526  :  cputs  (  wrk  ) ; 

527  :  set— mdm  (  mparm  ) ; 

528  :  return  n  ; 

529  :  } 

530  : 

531  :  #define  PAREVN  0x18  /*  MCR  bits  for  commands  */ 

532  :  tdefine  PARODD  0x10 

533  :  #define  PAROFF  0x00 

Figure  6-8.  Continued. 


/*  initialize  comm  port  stuff 


/*  firstime  flag  */ 

/*  8,N,1  */ 

/*  1200  baud  */ 

/*  baudrate  codes  */ 

/*  n  is  baud  rate  */ 


/*  get  keyboard  character 

returns  -1  if  none  present  */ 

/*  no  char  at  all  */ 
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534 

tdefine  STOP2  0x40 

535 

#define  WORDS  0x03 

536 

#define  WORD7  0x02 

537 

#define  WORD6  0x01 

538 

539 

Set-Parity  (  n  )  int  n  ; 

/* 

n  is  parity  code 

*/ 

540 

{  static  int  mmode; 

541 

if  (  n  ==  1  ) 

542 

nunode  =  (  WORDS  i  PAROFF  )  ; 

/* 

off 

*/ 

543 

else 

544 

if  (  n  ==  2  ) 

545 

mmode  =  (  WORD 7  !  PAREVN  ) ; 

/* 

on  and  even 

*/ 

546 

else 

547 

if  (  n  ==  3  ) 

548 

mmode  =  (  WORD 7  |  PARODD  ) ; 

/* 

on  and  odd 

*/ 

549 

else 

550 

return  0; 

/* 

invalid  code 

551 

mparm  =  (  mparm  &  OxEO  )  +  mmode; 

552 

sprintf  (  wrk,  "Parity  is  %s\r\n", 

(  n  == 

=  1  ?  "OFF"  : 

553 

(  n  == 

=  2  ?  "EVEN"  :  "ODD" 

)  )  )  ; 

554 

4  cputs  (  wrk  ) ; 

555 

set_mdm  (  mparm  ) ; 

556 

return  n  ; 

557 

} 

558 

559 

Write-Modem  (  c  )  char  c  ; 

/* 

return  1  if  ok,  else 

0 

*/ 

560 

{  wrtmdm  (  c  ) ; 

561 

return  (  1  ) ; 

/* 

never  any  error 

*/ 

562 

} 

563 

564 

Read-Modem  () 

565 

{  return  (  rdmdm  ()); 

/* 

from  int  bfr 

*/ 

566 

} 

567 

568 

;  void  Term— Comm  ()  /*  uninstall  comm  port  drivers 

*/ 

569 

{  u-m  ( )  ; 

570 

} 

571 

572 

/*  end  of  cterm.c  */ 

Figure  6-8.  Continued. 


CTERM  features  file-capture  capabilities,  a  simple  yet  effective  script  language,  and  a 
number  of  stub  (that  is,  incompletely  implemented)  actions,  such  as  emulation  of  the  VT52 
and  vnOO  series  terminals,  indicating  various  directions  in  which  it  can  be  developed. 

The  names  of  a  script  file  and  a  capture  file  can  be  passed  to  CTERM  in  the  command  line. 
If  no  filename  extensions  are  included,  the  default  for  the  script  file  is  .SCR  and  that  for  the 
capture  file  is  .CAP.  If  extensions  are  given,  they  override  the  default  values.  The  capture 
feature  can  be  invoked  only  if  a  filename  is  supplied  in  the  command  line,  but  a  script  file 
can  be  called  at  any  time  via  the  Esc  command  sequence,  and  one  script  file  can  call  for 
another  with  the  same  feature. 
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The  functions  included  in  CTERM.C  are  listed  and  summarized  in  Table  6-13. 

Table  6-13.  CTERM.C  Functions. 


lines 

Name 

Description 

1-5 

Program  documentation. 

7-11 

Include  files. 

12-20 

Definitions. 

22-43 

Global  data  areas. 

45 

External  prototype  declaration. 

47-49 

WantsJTo^AbortO 

Checks  for  Ctrl-Break  or  Ctrl-C  being  pressed. 

52-165 

mainO 

Main  program  loop;  includes  modem  engine  and 
sequential  state  machine  to  decode  remote 
commands. 

167-297 

docmdO 

Gets,  interprets,  and  performs  local  (console  or 
script)  command. 

299-304 

kbd^waitO 

Waits  for  input  from  console  or  script  file. 

306-334 

kbJileO 

Gets  keystroke  from  console  or  script;  returns  EOF 
if  no  character  available. 

336-362 

escQ 

Translates  script  escape  sequence. 

364-370 

getfilO 

Gets  name  of  script  file  and  opens  the  file. 

getnamO 

Gets  string  from  console  or  script  into  designated 
buffer. 

384-393 

addextO 

Checks  buffer  for  extension;  adds  one  if  none 
given. 

395-398 

put_capO 

Writes  character  to  capture  file  if  capture  in  effect. 

400-406 

cap^flushO 

Closes  capture  file  and  terminates  capture  mode  if 
capture  in  effect. 

408-411 

Timer  data  locations. 

413-425 

getmr() 

Returns  time  since  midnight,  in  milliseconds. 

427-432 

DelayO 

Sleeps  n  milliseconds. 

434-436 

Start^TimerC) 

Sets  timer  for  n  seconds. 

438-440 

Timer-ExpiredQ 

Checks  timer  versus  clock. 

442-445 

Set^VidO 

Initializes  video  data. 

4A1-A52 

locateQ 

Positions  cursor  on  display. 

454-456 

deolQ 

Deletes  to  end  of  line. 

458-468 

deosO 

Deletes  to  end  of  screen. 

470-472 

clsO 

Clears  screen. 

474-478 

cursorO 

Turns  cursor  on  or  off 

480-485 

rewidO 

Toggles  inverse/normal  video  display  attributes. 

487-492 

putchxO 

Writes  char  to  display  using  putchO  (Microsoft  C 

library). 


(more) 
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Table  6-13.  Continued. 


Lines 

Name 

Description 

494-500 

502-504 

Read^eyboardO 

Gets  keystroke  from  keyboard. 

Modem  data  areas. 

506-512 

514-515 

Init^CommO 

Installs  ISR  and  so  forth  and  initializes  modem. 
Baud-rate  definitions. 

517-529 

531-537 

Set^BaudO 

Changes  bps  rate  of  UART. 

Parity,  WL  definitions. 

539-557 

Set^ParityO 

Establishes  UART  parity  mode. 

559-562 

Write^ModemO 

Sends  character  to  UART. 

564-566 

Read^ModemO 

Gets  character  from  ISR’s  buffer. 

568-570 

Term_Comm() 

Uninstalls  ISR  and  so  forth  and  restores  original 
vectors. 

For  communication  with  the  console,  CTERM  uses  the  special  Microsoft  C  library  func¬ 
tions  defined  by  CONIO.H,  augmented  with  the  functions  in  the  CH2.ASM  handler.  Much 
of  the  code  may  require  editing  if  used  with  other  compilers.  CTERM  also  uses  the  func¬ 
tion  prototype  file  CTERM.H,  listed  in  Figure  6-9,  to  optimize  function  calling  within  the 
program. 

/*  CTERM.H  -  function  prototypes  for  CTERM. C  */ 

int  Wants_To_Abort (void) ; 

void  main (int  , char  *  *); 

int  docmd (void) ; 

int  kbd_wait (void) ; 

int  kb_file (void) ; 

int  esc (void); 

FILE  *getfil (void) ; 

void  getnam(char  *,int  ); 

char  *addext (char  *,char  *) ; 

void  put_cap(char  ); 

void  cap_f lush (void) ; 

long  getmr (void) ; 

void  Delay (int  ); 

void  Start-Timer (int  ); 

int  Timer-Expired (void) ; 

int  Set— Vid (void) ; 

void  locate (int  , int  ); 

void  deol (void) ; 

void  deos (void) ; 

void  els (void) ; 

void  cursor (int  ); 

void  revvid(int  ); 

int  putchx(char  ); 

Figure  6-9-  CTERM.H.  (more) 
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int  Read-Keyboard (void) ; 
void  Init— Comm (void) ; 
int  Set_Baud(int  ); 
int  Set-Parity (int  ); 
int  Write— Modem (char  ); 
int  Read-Modem (void)  ; 
void  Term— Comm (void) ; 

/*  CHI .ASM  functions  -  modem  interfacing  */ 

void  i— m(void); 

void  set— mdm (int) ; 

void  wrtmdm(int); 

void  Send  Byte (int); 

int  rdmdm(void); 

void  u— m(void); 

/*  CHI  A. ASM  functions  -  exception  handlers  */ 
void  set— int  (void) ; 
void  rst— int  (void) ; 
int  broke  (void) ; 

/*  CH2.ASM  functions  -  video  interfacing  */ 

void  _i— V (void) ; 

int  _wrpos(int,  int); 

void  -deol (void) ; 

void  —cls (void) ; 

int  —color (int,  int); 

Figure  6-9.  Continued. 

Program  execution  begins  at  the  entry  to  main(X  line  52.  CTERM  first  checks  (lines  56 
through  59)  whether  any  filenames  were  passed  in  the  command  line;  if  they  were, 

CTERM  opens  the  corresponding  files.  Next,  the  program  installs  the  exception  handler 
(line  60),  initializes  the  video  handler  (line  6l),  clears  the  display  (line  62),  and  announces 
its  presence  (lines  63  and  64).  The  serial  driver  is  installed  and  initialized  to  1200  bps  and 
no  parity  (lines  65  through  67),  and  the  program  enters  its  main  modem-engine  loop 
(lines  68  through  159). 

This  loop  is  functionally  the  same  as  that  used  in  ENGINE,  but  it  has  been  extended  to 
detect  an  Esc  from  the  keyboard  as  signalling  the  start  of  a  local  command  sequence  (lines 
70  through  73)  and  to  include  a  state-machine  technique  (lines  80  through  153)  to  recog¬ 
nize  incoming  escape  sequences,  such  as  the  VT52  or  VTIOO  codes.  To  specify  a  local  com¬ 
mand  from  the  keyboard,  press  the  Escape  (Esc)  key,  then  the  first  letter  of  the  local 
command  desired.  After  the  local  command  has  been  selected,  press  any  key  (such  as 
Enter  or  the  spacebar)  to  continue.  To  get  a  listing  of  all  the  commands  available,  press 
Esc-H. 

The  kb_file()  routine  of  CTERM  (called  in  the  main  loop  at  line  69)  can  get  its  input  from 
either  a  script  file  or  the  keyboard.  If  a  script  file  is  open  (lines  308  through  330),  it  is  used 
until  EOF  is  reached  or  until  the  operator  presses  Ctrl-C  to  stop  script-file  input.  Otherwise, 
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input  is  taken  from  the  keyboard  (lines  331  and  332).  If  a  script  file  is  in  use,  its  input  is 
echoed  to  the  display  (lines  325  through  329)  if  the  V  command  has  been  given. 

To  permit  the  Esc  character  itself  to  be  placed  in  script  files,  the  backslash  (\)  character 
serves  as  a  secondary  escape  signal.  When  a  backslash  is  detected  (lines  323  and  324)  in 
the  input  stream,  the  next  character  input  is  translated  according  to  the  following  rules: 


Character 

Interpretation 

E  or  e 

Translates  to  Esc. 

N  or  n 

Translates  to  Linefeed. 

Ror  r 

Translates  to  Enter  (CR). 

T  or  t 

Translates  to  Tab. 

A 

Causes  the  next  character  input  to  be  converted  into  a  control  character. 

Any  other  character,  including  another  \ ,  is  not  translated  at  all. 

When  the  Esc  character  is  detected  from  either  the  console  or  a  script  file,  the  docmdQ 
function  (lines  l67  through  297)  is  called  to  prompt  for  and  decode  the  next  input  charac¬ 
ter  as  a  command  and  to  perform  appropriate  actions.  Valid  command  characters,  and  the 
actions  they  invoke,  are  as  follows: 


Command 

Character  Action 

D  Delay  0-9  seconds,  then  proceed.  Must  be  followed  by  a  decimal 

digit  that  indicates  how  long  to  delay. 

Set  EVEN  parity. 

Set  (fast)  1200  baud. 

Display  list  of  valid  commands. 

Set  no  parity. 

Set  ODD  parity. 

Quit;  return  to  MS-DOS  command  prompt. 

Reset  modem. 

Set  (slow)  300  baud. 

Use  script  file  (CTERM  prompts  for  filename). 

Verify  file  input.  Echoes  each  script-file  byte. 

Wait  for  character;  the  next  input  character  is  the  one  that  must  be 
matched. 

Any  other  character  input  after  an  Esc  and  the  resulting  Command  prompt  generates  the 
message  Don’t  know X  (where  X  stands  for  the  actual  input  character)  followed  by  the 
prompt  Use  ‘H’ command  for  Help. 


E 

F 

H 

N 

O 

Q 

R 

S 

u 

V 

w 
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If  input  is  taken  from  a  script  and  the  V  flag  is  off,  docmdQ  performs  its  task  quietly,  with 
no  output  to  the  screen.  If  input  is  received  from  the  console,  however,  the  command  let¬ 
ter,  followed  by  a  descriptive  phrase,  is  echoed  to  the  screen.  Input,  detection,  and  execu¬ 
tion  of  the  local  commands  are  accomplished  much  as  in  CDVUTL,  by  way  of  a  large 
switchQ  statement  (lines  178  through  290). 

Although  the  listed  commands  are  only  a  subset  of  the  features  available  in  CDVUTL  for 
the  device-driver  program,  they  are  more  than  adequate  for  creating  useful  scripts.  The 
predecessor  of  CTERM  (DT115.EXE),  which  included  the  CompuServe  B-Protocol  file- 
transfer  capability  but  had  no  additional  commands,  has  been  in  use  since  early  1986  to 
handle  automatic  uploading  and  downloading  of  files  from  the  CompuServe  Information 
Service  by  means  of  script  files.  In  conjunction  with  an  auto-dialing  modem,  DT115.EXE 
handles  the  entire  transaction,  from  login  through  logout,  without  human  intervention. 

All  the  bits  and  pieces  of  CTERM  are  put  together  by  assembling  the  three  handlers 
with  MASM,  compiling  CTERM  with  Microsoft  C,  and  linking  all  four  object  modules  into 
an  executable  file.  Figure  6-10  shows  the  complete  sequence  and  also  the  three  ways  of 
using  the  finished  program. 

Compiling: 

OMASM  CHI;  <Enter> 

OMASM  CHI  A;  <Enter> 

OMASM  CH2;  <Enter> 

OMSC  CTERM;  <Enter> 

linking: 

OLINK  CTERM+CH1+CH1A+CH2;  <Enter> 

Use: 

(no  files) 

OCTERM  <Enter> 

or 

(script  only) 

OCTERM  scriptfile  <Enter> 

or 

OCTERM  scriptfile  capturefile  <Enter> 

Figure  6-10.  Putting  CTERM  together  and  using  it. 


Jim  Kyle 
Chip  Rabinowitz 
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Article  7 

File  and  Record  Management 


The  core  of  most  application  programs  is  the  reading,  processing,  and  writing  of  data 
stored  on  magnetic  disks.  This  data  is  organized  into  files,  which  are  identified  by  name; 
the  files,  in  turn,  can  be  organized  by  grouping  them  into  directories.  Operating  systems 
provide  application  programs  with  services  that  allow  them  to  manipulate  these  files  and 
directories  without  regard  to  the  hardware  characteristics  of  the  disk  device.  Thus,  applica¬ 
tions  can  concern  themselves  solely  with  the  form  and  content  of  the  data,  leaving  the 
details  of  the  data’s  location  on  the  disk  and  of  its  retrieval  to  the  operating  system. 

The  disk  storage  services  provided  by  an  operating  system  can  be  categorized  into  file 
functions  and  record  functions.  The  file  functions  operate  on  entire  files  as  named 
entities,  whereas  the  record  functions  provide  access  to  the  data  contained  within  files. 

(In  some  systems,  an  additional  class  of  directory  functions  allows  applications  to  deal 
with  collections  of  files  as  well.)  This  article  discusses  the  MS-DOS  function  calls  that 
allow  an  application  program  to  create,  open,  close,  rename,  and  delete  disk  files;  read 
data  from  and  write  data  to  disk  files;  and  inspect  or  change  the  information  (such  as 
attributes  and  date  and  time  stamps)  associated  with  disk  filenames  in  disk  directories. 

See  also  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Structure  of  ms-dos: 
MS-DOS  Storage  Devices;  Programming  for  ms-dos:  Disk  Directories  and  Volume  Labels. 


Historical  Perspective 

Current  versions  of  MS-DOS  provide  two  overlapping  sets  of  file  and  record  management 
services  to  support  application  programs:  the  handle  functions  and  the  file  control  block 
(FCB)  functions.  Both  sets  are  available  through  Interrupt  21H  (Table  7-1).  See  SYSTEM 
CALLS:  Interrupt  21h.  The  reasons  for  this  surprising  duplication  are  strictly  historical. 

The  earliest  versions  of  MS-DOS  used  FCBs  for  all  file  and  record  access  because  CP/M, 
which  was  the  dominant  operating  system  on  8-bit  microcomputers,  used  FCBs.  Microsoft 
chose  to  maintain  compatibility  with  CP/M  to  aid  programmers  in  converting  the  many 
existing  CP/M  application  programs  to  the  l6-bit  MS-DOS  environment;  consequently, 
MS-DOS  versions  1.x  included  a  set  of  FCB  functions  that  were  a  functional  superset  of 
those  present  in  CP/M.  As  personal  computers  evolved,  however,  the  FCB  access  method 
did  not  lend  itself  well  to  the  demands  of  larger,  faster  disk  drives. 

Accordingly,  MS-DOS  version  2.0  introduced  the  handle  functions  to  provide  a  file  and 
record  access  method  similar  to  that  found  in  UNIX/XENIX.  These  functions  are  easier  to 
use  and  more  flexible  than  their  FCB  counterparts  and  fully  support  a  hierarchical  (tree¬ 
like)  directory  structure.  The  handle  functions  also  allow  character  devices,  such  as  the 
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console  or  printer,  to  be  treated  for  some  purposes  as  though  they  were  files.  MS-DOS  ver¬ 
sion  3.0  introduced  additional  handle  functions,  enhanced  some  of  the  existing  handle 
functions  for  use  in  network  environments,  and  provided  improved  error  reporting  for 
all  functions. 

The  handle  functions,  which  offer  far  more  capability  and  performance  than  the  FCB 
functions,  should  be  used  for  all  new  applications.  Therefore,  they  are  discussed  first  in 
this  article. 

Table  7-1.  Interrupt  21H  Function  Calls  for  File  and  Record  Management. 


Handle 

FCB 

Operation 

Function 

Function 

Create  file. 

3GH 

16H 

Create  new  file. 

5BH 

Create  temporary  file. 

5AH 

Open  file. 

3DH 

OFH 

Close  file. 

3EH 

lOH 

Delete  file. 

41H 

13H 

Rename  file. 

56H 

17H 

Perform  sequential  read. 

3FH 

14H 

Perform  sequential  write. 

40H 

15H 

Perform  random  record  read. 

3FH 

21H 

Perform  random  record  write. 

40H 

22H 

Perform  random  block  read. 

27H 

Perform  random  block  write. 

28H 

Set  disk  transfer  area  address. 

lAH 

Get  disk  transfer  area  address. 

2FH 

Parse  filename. 

29H 

Position  read/write  pointer. 

Set  random  record  number. 

42H 

24H 

Get  file  size. 

42H 

23H 

Get/Set  file  attributes. 

43H 

Get/Set  date  and  time  stamp. 

57H 

Duplicate  file  handle. 

45H 

Redirect  file  handle. 

46H 
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Using  the  Handle  Functions 

The  initial  link  between  an  application  program  and  the  data  stored  on  disk  is  the  name  of 
a  disk  file  in  the  form 

drive:path\  filename.ext 

where  drive  designates  the  disk  on  which  the  file  resides,  path  specifies  the  directory 
on  that  disk  in  which  the  file  is  located,  and  filename.ext  identifies  the  file  itself.  If  drive 
and/or  path  is  omitted,  MS-DOS  assumes  the  default  disk  drive  and  current  directory. 
Examples  of  acceptable  pathnames  include 

C:  \  PAYROLL\TAXES.DAT 

LETTERS\MEMO.TXT 

BUDGET.DAT 

Pathnames  can  be  hard-coded  into  a  program  as  part  of  its  data.  More  commonly,  how¬ 
ever,  they  are  entered  by  the  user  at  the  keyboard,  either  as  a  command-line  parameter  or 
in  response  to  a  prompt  from  the  program.  If  the  pathname  is  provided  as  a  command¬ 
line  parameter,  the  application  program  must  extract  it  from  the  other  information  in  the 
command  line.  Therefore,  to  allow  a  program  to  distinguish  between  pathnames  and 
other  parameters  when  the  two  are  combined  in  a  command  line,  the  other  parameters, 
such  as  switches,  usually  begin  with  a  slash  (/)  or  dash  (-)  character. 

All  handle  functions  that  use  a  pathname  require  the  name  to  be  in  the  form  of  an  ASCIIZ 
string — that  is,  the  name  must  be  terminated  by  a  null  (zero)  byte.  If  the  pathname  is 
hard-coded  into  a  program,  the  null  byte  must  be  part  of  the  ASCIIZ  string.  If  the  path¬ 
name  is  obtained  from  keyboard  input  or  from  a  command-line  parameter,  the  null  byte 
must  be  appended  by  the  program.  See  Opening  an  Existing  File  below. 

To  use  a  disk  file,  a  program  opens  or  creates  the  file  by  calling  the  appropriate  MS-DOS 
function  with  the  ASCIIZ  pathname.  MS-DOS  checks  the  pathname  for  invalid  characters 
and,  if  the  open  or  create  operation  is  successful,  returns  a  l6-bit  handle,  or  identification 
code,  for  the  file.  The  program  uses  this  handle  for  subsequent  operations  on  the  file,  such 
as  record  reads  and  writes. 

The  total  number  of  handles  for  simultaneously  open  files  is  limited  in  two  ways.  First,  the 
per-process  limit  is  20  file  handles.  The  process’s  first  five  handles  are  always  assigned  to 
the  standard  devices,  which  default  to  the  CON,  AUX,  and  PRN  character  devices: 


Handle  Service 

0  Standard  input 

1  Standard  output 

2  Standard  error 

3  Standard  auxiliary 

4  Standard  list 


Default 

Keyboard  (CON) 

Video  display  (CON) 

Video  display  (CON) 

First  communications  port  (AUX) 
First  parallel  printer  port  (PRN) 
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Ordinarily,  then,  a  process  has  only  15  handles  left  from  its  initial  allotment  of  20;  however, 
when  necessary,  the  5  standard  device  handles  can  be  redirected  to  other  files  and  devices 
or  closed  and  reused. 

In  addition  to  the  per-process  limit  of  20  file  handles,  there  is  a  system-wide  limit. 

MS-DOS  maintains  an  internal  table  that  keeps  track  of  all  the  files  and  devices  opened 
with  file  handles  for  all  currently  active  processes.  The  table  contains  such  information  as 
the  current  file  pointer  for  read  and  write  operations  and  the  time  and  date  of  the  last  write 
to  the  file.  The  size  of  this  table,  which  is  set  when  MS-DOS  is  initially  loaded  into  memory, 
determines  the  system-wide  limit  on  how  many  files  and  devices  can  be  open  simulta¬ 
neously.  The  default  limit  is  8  files  and  devices;  thus,  this  system-wide  limit  usually 
overrides  the  per-process  limit. 

To  increase  the  size  of  MS-DOS's  internal  handle  table,  the  statement  FILES=nnn  can  be 
included  in  the  CONFIG.SYS  file.  (CONFIG.SYS  settings  take  effect  the  next  time  the  sys¬ 
tem  is  turned  on  or  restarted.)  The  maximum  value  for  FILES  is  99  in  MS-DOS  versions  2.x 
and  255  in  versions  3.x.  See  USER  COMMANDS:  config.sys:  files. 

Error  handling  and  the  handle  functions 

When  a  handle-based  file  function  succeeds,  MS-DOS  returns  to  the  calling  program  with 
the  carry  flag  clear.  If  a  handle  function  fails,  MS-DOS  sets  the  carry  flag  and  returns  an 
error  code  in  the  AX  register.  The  program  should  check  the  carry  flag  after  each  opera¬ 
tion  and  take  whatever  action  is  appropriate  when  an  error  is  encountered.  Table  7-2  lists 
the  most  frequently  encountered  error  codes  for  file  and  record  I/O  (exclusive  of  network 
operations). 

Table  7-2.  Frequently  Encountered  Error  Diagnostics  for  File  and  Record 
Management. 


Code 

Error 

02 

File  not  found 

03 

Path  not  found 

04 

Too  many  open  files  (no  handles  left) 

05 

Access  denied 

06 

Invalid  handle 

11 

Invalid  format 

12 

Invalid  access  code 

13 

Invalid  data 

15 

Invalid  disk  drive  letter 

17 

Not  same  device 

18 

No  more  files 

The  error  codes  used  by  MS-DOS  in  versions  3.0  and  later  are  a  superset  of  the  MS-DOS 
version  2.0  error  codes.  See  APPENDIX  B:  Critical  Error  Codes;  APPENDIX  C:  Extended 
Error  Codes.  Most  MS-DOS  version  3  error  diagnostics  relate  to  network  operations, 
which  provide  the  program  with  a  greater  chance  for  error  than  does  a  single-user  system. 


250  The  MS-DOS  Encyclopedia 


Article  7:  File  and  Record  Management 


Programs  that  are  to  run  in  a  network  environment  need  to  anticipate  network  problems. 
For  example,  the  server  can  go  down  while  the  program  is  using  shared  files. 

Under  MS-DOS  versions  3.x,  a  program  can  also  use  Interrupt  21H  Function  59H  (Get 
Extended  Error  Information)  to  obtain  more  details  about  the  cause  of  an  error  after  a 
failed  handle  function.  The  information  returned  by  Function  59H  includes  the  type  of 
device  that  caused  the  error  and  a  recommended  recovery  action. 

Warning;  Many  file  and  record  I/O  operations  discussed  in  this  article  can  result  in  or  be 
affected  by  a  hardware  (critical)  error.  Such  errors  can  be  intercepted  by  the  program  if  it 
contains  a  custom  critical  error  exception  handler  (Interrupt  24H).  See  PROGRAMMING 
IN  THE  MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Exception  Handlers. 

Creating  a  file 

MS-DOS  provides  three  Interrupt  21H  handle  functions  for  creating  files: 


Function  Name 

3CH  Create  File  with  Handle  (versions  2.0  and  later) 

5AH  Create  Temporary  File  (versions  3.0  and  later) 

5BH  Create  New  File  (versions  3.0  and  later) 

Each  function  is  called  with  the  segment  and  offset  of  an  ASCII2  pathname  in  the  DS:DX 
registers  and  the  attribute  to  be  assigned  to  the  new  file  in  the  CX  register.  The  possible 
attribute  values  are 


Code  Attribute 

OOH  Normal  file 

OlH  Read-only  file 

02H  Hidden  file 

04H  System  file 

Files  with  more  than  one  attribute  can  be  created  by  combining  the  values  listed  above’ 

For  example,  to  create  a  file  that  has  both  the  read-only  and  system  attributes,  the  value 
05H  is  placed  in  the  CX  register. 

If  the  file  is  successfully  created,  MS-DOS  returns  a  file  handle  in  AX  that  must  be  used  for 
subsequent  access  to  the  new  file  and  sets  the  file  read/write  pointer  to  the  beginning  of 
the  file;  if  the  file  is  not  created,  MS-DOS  sets  the  carry  flag  (CF)  and  returns  an  error  code 
in  AX. 

Function  3CH  is  the  only  file-creation  function  available  under  MS-DOS  versions  2.x.  It 
must  be  used  with  caution,  however,  because  if  a  file  with  the  specified  name  already 
exists.  Function  3CH  will  open  it  and  truncate  it  to  zero  length,  eradicating  the  previous 
contents  of  the  file.  This  complication  can  be  avoided  by  testing  for  the  previous  existence 
of  the  file  with  an  open  operation  before  issuing  the  create  call. 
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Under  MS-DOS  versions  3.0  and  later,  Function  5BH  is  the  preferred  function  in  most  cases 
because  it  will  fail  if  a  file  with  the  same  name  already  exists.  In  networking  environments, 
this  function  can  be  used  to  implement  semaphores,  allowing  the  synchronization  of  pro¬ 
grams  running  in  different  network  nodes. 

Function  5AH  is  used  to  create  a  temporary  work  file  that  is  guaranteed  to  have  a  unique 
name.  This  capability  is  important  in  networking  environments,  where  several  copies  of 
the  same  program,  running  in  different  nodes,  may  be  accessing  the  same  logical  disk 
volume  on  a  server.  The  function  is  passed  the  address  of  a  buffer  that  can  contain  a  drive 
and/or  path  specifying  the  location  for  the  created  file.  MS-DOS  generates  a  name  for  the 
created  file  that  is  a  sequence  of  alphanumeric  characters  derived  from  the  current  time 
and  returns  the  entire  ASCIIZ  pathname  to  the  program  in  the  same  buffer,  along  with  the 
file’s  handle  in  AX.  The  program  must  save  the  filename  so  that  it  can  delete  the  file  later,  if 
necessary;  the  file  created  with  Function  5AH  is  not  destroyed  when  the  program  exits. 

Example:  Create  a  file  named  MEMO.TXT  in  the  \  LETTERS  directory  on  drive  C  using 
Function  3CH.  Any  existing  file  with  the  same  name  is  truncated  to  zero  length  and 
opened. 

fname  db  ' C : \LETTERS\MEMO. TXT ’ , 0 

fhandle  dw  ? 


mov 

mov 

mov 

xor 

mov 

int 

jc 

mov 


Example:  Create  a  temporary  file  using  Function  5AH  and  place  it  in  the  \TEMP  directory 
on  drive  C.  MS-DOS  appends  the  filename  it  generates  to  the  original  path  in  the  buffer 
named  fname.  The  resulting  file  specification  can  be  used  later  to  delete  the  file. 

fname  db  'C:\TEMP\'  ;  generated  ASCIIZ  filename 

db  13  dup  (0)  ;  is  appended  by  MS-DOS 

fhandle  dw  ? 


(more) 


dx,seg  fname  ;  DS:DX  =  address  of 

ds,dx  ;  pathname  for  file 

dx, offset  fname 

cx,cx  ;  CX  =  normal  attribute 

ah,3ch  ;  Function  3CH  =  create 

21 h  ;  transfer  to  MS-DOS 

error  ;  jump  if  create  failed 

fhandle, ax  ;  else  save  file  handle 
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mov  dx,seg  fname 

mov  ds ,  dx 

mov  dx, offset  fname 

xor  cx,cx 

mov  ah,5ah 

int  21 h 

jc  error 

mov  f handle, ax 


Opening  an  existing  file 

Function  3DH  (Open  File  with  Handle)  opens  an  existing  normal,  system,  or  hidden  file 
in  the  current  or  specified  directory.  When  calling  Function  3DH,  the  program  supplies  a 
pointer  to  the  ASCIIZ  pathname  in  the  DS:DX  registers  and  a  1-byte  access  code  in  the  AL 
register.  This  access  code  includes  the  read/write  permissions,  the  file-sharing  mode,  and 
an  inheritance  flag.  The  bits  of  the  access  code  are  assigned  as  follows: 


;  DS:DX  =  address  of 
;  path  for  temporary  file 

;  CX  =  normal  attribute 
;  Function  5AH  =  create 
;  temporary  file 
;  transfer  to  MS-DOS 
;  jump  if  create  failed 
;  else  save  file  handle 


Bit(s)  Description 

0-2  Read/write  permissions  (versions  2.0  and  later) 

3  Reserved 

4-6  File-sharing  mode  (versions  3.0  and  later) 

7  Inheritance  flag  (versions  3.0  and  later) 

The  read/write  permissions  field  of  the  access  code  specifies  how  the  file  will  be  used  and 
can  take  the  following  values: 


Bits  0-2  Description 

000  Read  permission  desired 

001  Write  permission  desired 

010  Read  and  write  permission  desired 

For  the  open  to  succeed,  the  permissions  field  must  be  compatible  with  the  file’s  attribute 
byte  in  the  disk  directory.  For  example,  if  the  program  attempts  to  open  an  existing  file 
that  has  the  read-only  attribute  when  the  permissions  field  of  the  access  code  byte  is  set  to 
write  or  read/write,  the  open  function  will  fail  and  an  error  code  will  be  returned  in  AX. 

The  sharing-mode  field  of  the  access  code  byte  is  important  in  a  networking  environment. 
It  determines  whether  other  programs  will  also  be  allowed  to  open  the  file  and,  if  so, 
what  operations  they  will  be  allowed  to  perform.  Following  are  the  possible  values  of  the 
file-sharing  mode  field: 
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Bits  4-6  Description 

000  Compatibility  mode.  Other  programs  can  open  the  file  and  perform  read  or 

write  operations  as  long  as  no  process  specifies  any  sharing  mode  other  than 
compatibility  mode. 

001  Deny  all.  Other  programs  cannot  open  the  file. 

010  Deny  write.  Other  programs  cannot  open  the  file  in  compatibility  mode  or 

with  write  permission. 

01 1  Deny  read.  Other  programs  cannot  open  the  file  in  compatibility  mode  or  with 

read  permission. 

100  Deny  none.  Other  programs  can  open  the  file  and  perform  both  read  and 

write  operations  but  cannot  open  the  file  in  compatibility  mode. 

When  file-sharing  support  is  active  (that  is,  SHARE.EXE  has  previously  been  loaded), 
the  result  of  any  open  operation  depends  on  both  the  contents  of  the  permissions  and  file¬ 
sharing  fields  of  the  access  code  byte  and  the  permissions  and  file-sharing  requested  by 
other  processes  that  have  already  successfully  opened  the  file. 

The  inheritance  bit  of  the  access  code  byte  controls  whether  a  child  process  will  inherit 
that  file  handle.  If  the  inheritance  bit  is  cleared,  the  child  can  use  the  inherited  handle  to 
access  the  file  without  performing  its  own  open  operation.  Subsequent  operations  per¬ 
formed  by  the  child  process  on  inherited  file  handles  also  affect  the  file  pointer  associated 
with  the  parent’s  file  handle.  If  the  inheritance  bit  is  set,  the  child  process  does  not  inherit 
the  handle. 

If  the  file  is  opened  successfully,  MS-DOS  returns  its  handle  in  AX  and  sets  the  file  read/ 
write  pointer  to  the  beginning  of  the  file;  if  the  file  is  not  opened,  MS-DOS  sets  the  carry 
flag  and  returns  an  error  code  in  AX. 

Example:  Copy  the  first  parameter  from  the  program’s  command  tail  in  the  program 
segment  prefix  (PSP)  into  the  array  /name  and  append  a  null  character  to  form  an  ASCIIZ 
filename.  Attempt  to  open  the  file  with  compatibility  sharing  mode  and  read/write  access. 
If  the  file  does  not  already  exist,  create  it  and  assign  it  a  normal  attribute. 

cmdtail  equ  80h  ;  PSP  offset  of  command  tail 

fname  db  64  dup  (?) 

fhandle  dw  ? 


;  assume  that  DS  already 
;  contains  segment  of  PSP 


(more) 
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mov 

si, cmdtail 

mov 

di,seg  fname 

mov 

es,  di 

mov 

cld 

di, offset  fname 

lodsb 

or 

al,  al 

jz 

error 

label  1  : 

lodsb 

cmp  al,20h 

jz  labell 

label2: 

cmp  al/Odh 

jz  labels 

cmp  al,20h 

jz  labels 

stosb 
lodsb 

jmp  label2 

labels : 

xor  al,al 

stosb 


mov  dx,seg  fname 

mov  ds , dx 

mov  dx, offset  fname 

mov  ax,Sd02h 

int  21 h 

jnc  label4 

cmp  ax ,  2 

jnz  error 

xor  cx,cx 

mov  ah,Sch 

int  21 h 

jc  error 

label4: 

mov  f handle, ax 


prepare  to  copy  filename. . . 
DS:SI  =  command  tail 
ES:DI  =  buffer  to  receive 
filename  from  command  tail 

safety  first! 

check  length  of  command  tail 

jump,  command  tail  empty 

scan  off  leading  spaces 
get  next  character 
is  it  a  space? 
yes,  skip  it 

look  for  terminator 
quit  if  return  found 

quit  if  space  found 
else  copy  this  character 
get  next  character 


store  final  NULL  to 
create  ASCIIZ  string 

now  open  the  file. . . 
DS:DX  =  address  of 
pathname  for  file 

Function  SDH  =  open  r/w 
transfer  to  MS-DOS 
jump  if  file  found 

error  2  =  file  not  found 
jump  if  other  error 
else  make  the  file... 

CX  =  normal  attribute 
Function  SCH  =  create 
transfer  to  MS-DOS 
jump  if  create  failed 

save  handle  for  file 


Closing  a  file 

Function  3EH  (Close  File)  closes  a  file  created  or  opened  with  a  file  handle  function.  The 
program  must  place  the  handle  of  the  file  to  be  closed  in  BX.  If  a  write  operation  was  per¬ 
formed  on  the  file,  MS-DOS  updates  the  date,  time,  and  size  in  the  file’s  directory  entry. 
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Closing  the  file  also  flushes  the  internal  MS-DOS  buffers  associated  with  the  file  to  disk 
and  causes  the  disk’s  file  allocation  table  (FAT)  to  be  updated  if  necessary. 

Good  programming  practice  dictates  that  a  program  close  files  as  soon  as  it  finishes 
using  them.  This  practice  is  particularly  important  when  the  file  size  has  been  changed,  to 
ensure  that  data  will  not  be  lost  if  the  system  crashes  or  is  turned  off  unexpectedly  by  the 
user.  A  method  of  updating  the  FAT  without  closing  the  file  is  outlined  below  under 
Duplicating  and  Redirecting  Handles. 

Reading  and  writing  with  handles 

Function  3FH  (Read  File  or  Device)  enables  a  program  to  read  data  from  a  file  or  device 
that  has  been  opened  with  a  handle.  Before  calling  Function  3FH,  the  program  must  set 
the  DS:DX  registers  to  point  to  the  beginning  of  a  data  buffer  large  enough  to  hold  the 
requested  transfer,  put  the  file  handle  in  BX,  and  put  the  number  of  bytes  to  be  read  in  CX. 
The  length  requested  can  be  a  maximum  of  65535  bytes.  The  program  requesting  the 
read  operation  is  responsible  for  providing  the  data  buffer. 

If  the  read  operation  succeeds,  the  data  is  read,  beginning  at  the  current  position  of  the 
file  read/write  pointer,  to  the  specified  location  in  memory.  MS-DOS  then  increments  its 
internal  read/write  pointer  for  the  file  by  the  length  of  the  data  transferred  and  returns 
the  length  to  the  calling  program  in  AX  with  the  carry  flag  cleared.  The  only  indication 
that  the  end  of  the  file  has  been  reached  is  that  the  length  returned  is  less  than  the  length 
requested.  In  contrast,  when  Function  3FH  is  used  to  read  from  a  character  device  that  is 
not  in  raw  mode,  the  read  will  terminate  at  the  requested  length  or  at  the  receipt  of  a  car¬ 
riage  return  character,  whichever  comes  first.  See  PROGRAMMING  IN  THE  MS-DOS 
ENVIRONMENT:  Programming  for  ms-dos:  Character  Device  Input  and  Output.  If  the 
read  operation  fails,  MS-DOS  returns  with  the  carry  flag  set  and  an  error  code  in  AX. 

Function  40H  (Write  File  or  Device)  writes  from  a  buffer  to  a  file  (or  device)  using  a  handle 
previously  obtained  from  an  open  or  create  operation.  Before  calling  Function  40H,  the 
program  must  set  DS:DX  to  point  to  the  beginning  of  the  buffer  containing  the  source  data, 
put  the  file  handle  in  BX,  and  put  the  number  of  bytes  to  write  in  CX.  The  number  of  bytes 
to  write  can  be  a  maximum  of  65535. 

If  the  write  operation  is  successful,  MS-DOS  puts  the  number  of  bytes  written  in  AX  and 
increments  the  read/write  pointer  by  this  value;  if  the  write  operation  fails,  MS-DOS  sets 
the  carry  flag  and  returns  an  error  code  in  AX. 

Records  smaller  than  one  sector  (512  bytes)  are  not  written  directly  to  disk.  Instead, 
MS-DOS  stores  the  record  in  an  internal  buffer  and  writes  it  to  disk  when  the  internal 
buffer  is  full,  when  the  file  is  closed,  or  when  a  call  to  Interrupt  21H  Function  ODH  (Disk 
Reset)  is  issued. 

Note:  If  the  destination  of  the  write  operation  is  a  disk  file  and  the  disk  is  full,  the  only 
indication  to  the  calling  program  is  that  the  length  returned  in  AX  is  not  the  same  as  the 
length  requested  in  CX.  Disk full  is  not  returned  as  an  error  with  the  carry  flag  set. 

A  special  use  of  the  Write  function  is  to  truncate  or  extend  a  file.  If  Function  40H  is  called 
with  a  record  length  of  zero  in  CX,  the  file  size  will  be  adjusted  to  the  current  location  of 
the  file  read/write  pointer. 
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Example:  Open  the  file  MYFILE.DAT,  create  the  file  MYFILE.BAK,  copy  the  contents  of 
the  .DAT  file  into  the  .BAK  file  using  512-byte  reads  and  writes,  and  then  close  both  files. 


filel 

db 

'MYFILE.DAT' 

,0 

file2 

db 

'MYFILE.BAK' 

/O 

handlel 

dw 

7 

;  handle 

for 

MYFILE.DAT 

handle? 

dw 

7 

;  handle 

for 

MYFILE.BAK 

buff 

db 

512  dup  (?) 

;  buffer 

for 

file  I/O 

mov  dx,seg  filel 

mov  ds,dx 

mov  dx, offset  filel 

mov  ax,3d00h 

int  21h 

jc  error 

mov  handle 1, ax 


mov  dx, offset  file2 

mov  cx,0 

mov  ah,3ch 

int  21h 

jc  error 

mov  handle2,ax 

loop: 

mov  dx, offset  buff 

mov  cx,512 

mov  bx, handle 1 

mov  ah,3fh 

int  21 h 

jc  error 

or  ax, ax 

jz  done 

mov  dx, offset  buff 

mov  cx,ax 

mov  bx,handle2 

mov  ah,40h 

int  21h 

jc  error 

cmp  ax,cx 

jne  error 

jmp  loop 


open  MYFILE.DAT... 

DS:DX  =  address  of  filename 


Function  3DH  =  open  (read-only) 
transfer  to  MS-DOS 
jump  if  open  failed 
save  handle  for  file 

create  MYFILE.BAK... 

DS:DX  =  address  of  filename 
CX  =  normal  attribute 
Function  3CH  =  create 
transfer  to  MS-DOS 
jump  if  create  failed 
save  handle  for  file 

read  MYFILE.DAT 

DS:DX  =  buffer  address 

CX  =  length  to  read 

BX  =  handle  for  MYFILE.DAT 

Function  3FH  =  read 

transfer  to  MS-DOS 

jump  if  read  failed 

were  any  bytes  read? 

no,  end  of  file  reached 

write  MYFILE.BAK 
DS:DX  =  buffer  address 
CX  =  length  to  write 
BX  =  handle  for  MYFILE.BAK 
Function  40H  =  write 
transfer  to  MS-DOS 
jump  if  write  failed 
was  write  complete? 
jump  if  disk  full 
continue  to  end  of  file 


(more) 
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done: 


mov 

bx, handle  1 

mov 

ah, 3eh 

int 

21h 

jc 

error 

mov 

bx, handle2 

mov 

ah, 3eh 

int 

21h 

jc 

error 

now  close  files... 
handle  for  MYFILE.DAT 
Function  3EH  =  close  file 
transfer  to  MS-DOS 
jump  if  close  failed 

handle  for  MYFILE.BAK 
Function  3EH  =  close  file 
transfer  to  MS-DOS 
jump  if  close  failed 


Positioning  the  read/wiite  pointer 

Function  42H  (Move  File  Pointer)  sets  the  position  of  the  read/write  pointer  associated 
with  a  given  handle.  The  function  is  called  with  a  signed  32-bit  offset  in  the  CX  and  DX 
registers  (the  most  significant  half  in  CX),  the  file  handle  in  BX,  and  the  positioning  mode 
in  AL: 


Mode  Significance 

00  Supplied  offset  is  relative  to  beginning  of  file. 

01  Supplied  offset  is  relative  to  current  position  of  read/write  pointer. 

02  Supplied  offset  is  relative  to  end  of  file. 

If  Function  42H  succeeds,  MS-DOS  returns  the  resulting  absolute  offset  (in  bytes)  of  the 
file  pointer  relative  to  the  beginning  of  the  file  in  the  DX  and  AX  registers,  with  the  most 
significant  half  in  DX;  if  the  function  fails,  MS-DOS  sets  the  carry  flag  and  returns  an  error 
code  in  AX. 

Thus,  a  program  can  obtain  the  size  of  a  file  by  calling  Function  42H  with  an  offset  of  zero 
and  a  positioning  mode  of  2.  The  function  returns  a  value  in  DX:AX  that  represents  the 
offset  of  the  end-of-file  position  relative  to  the  beginning  of  the  file. 

Example:  Assume  that  the  file  MYFILE.DAT  was  previously  opened  and  its  handle  is 
saved  in  the  variable  /handle.  Position  the  file  pointer  32768  bytes  from  the  beginning  of 
the  file  and  then  read  512  bytes  of  data  starting  at  that  file  position. 

fhandle  dw  ?  ;  handle  from  previous  open 

buff  db  512  dup  (?)  ;  buffer  for  data  from  file 


(more) 
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mov  cx,0 

mov  dx, 32768 

mov  bx, f handle 

mov  al,0 

mov  ah,42h 

int  21h 

jc  error 


mov  dx, offset  buff 

mov  cx,512 

mov  bx,f handle 

mov  ah, 3fh 

int  21 h 

jc  error 

cmp  ax, 51 2 

jne  error 


position  the  file  pointer. . . 

CX  =  high  part  of  file  offset  • 

DX  =  low  part  of  file  offset 

BX  =  handle  for  file 

AL  =  positioning  mode 

Function  42H  =  position 

transfer  to  MS-DOS 

jump  if  function  call  failed 

now  read  512  bytes  from  file 
DS:DX  =  address  of  buffer 
CX  =  length  of  512  bytes 
BX  =  handle  for  file 
Function  3FH  =  read 
transfer  to  MS-DOS 
jump  if  read  failed 
was  512  bytes  read? 
jump  if  partial  rec.  or  EOF 


Example:  Assume  that  the  file  MYFILE.DAT  was  previously  opened  and  its  handle  is  saved 
in  the  variable  /handle.  Find  the  size  of  the  file  in  bytes  by  positioning  the  file  pointer  to 
zero  bytes  relative  to  the  end  of  the  file.  The  returned  offset,  which  is  relative  to  the  begin¬ 
ning  of  the  file,  is  the  file’s  size. 

fhandle  dw  ?  ;  handle  from  previous  open 


mov  cx,0 

mov  dx ,  0 

mov  bx, fhandle 
mov  al,2 

mov  ah,42h 

int  21 h 

jc  error 


;  position  the  file  pointer 
;  to  the  end  of  file... 

;  CX  =  high  part  of  offset 
;  DX  =  low  part  of  offset 
;  BX  =  handle  for  file 
;  AL  =  positioning  mode 
/  Function  42H  =  position 
;  transfer  to  MS-DOS 
;  jump  if  function  call  failed 

;  if  call  succeeded,  DX:70C 
;  now  contains  the  file  size 


Other  handle  operations 

MS-DOS  provides  other  handle-oriented  functions  to  rename  (or  move)  a  file,  delete  a  file, 
read  or  change  a  file’s  attributes,  read  or  change  a  file’s  date  and  time  stamp,  and  duplicate 
or  redirect  a  file  handle.  The  first  three  of  these  are  “file-handle-like”  because  they  use  an 
ASCIIZ  string  to  specify  the  file;  however,  they  do  not  return  a  file  handle. 
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Renaming  a  file 

Function  56H  (Rename  File)  renames  an  existing  file  and/or  moves  the  file  from  one  loca¬ 
tion  in  the  hierarchical  file  structure  to  another.  The  file  to  be  renamed  cannot  be  a  hidden 
or  system  file  or  a  subdirectory  and  must  not  be  currently  open  by  any  process;  attempting 
to  rename  an  open  file  can  corrupt  the  disk.  MS-DOS  renames  a  file  by  simply  changing  its 
directory  entry;  it  moves  a  file  by  removing  its  current  directory  entry  and  creating  a  new 
entry  in  the  target  directory  that  refers  to  the  same  file.  The  location  of  the  file’s  actual 
data  on  the  disk  is  not  changed. 

Both  the  current  and  the  new  filenames  must  be  ASCIIZ  strings  and  can  include  a  drive 
and  path  specification;  wildcard  characters  (*  and  ?)  are  not  permitted  in  the  filenames. 

The  program  calls  Function  56H  with  the  address  of  the  current  pathname  in  the  DS:DX 
registers  and  the  address  of  the  new  pathname  in  ES:DI.  If  the  path  elements  of  the  two 
strings  are  not  the  same  and  both  paths  are  valid,  the  file  “moves”  from  the  source  direc¬ 
tory  to  the  target  directory.  If  the  paths  match  but  the  filenames  differ,  MS-DOS  simply 
modifies  the  directory  entry  to  reflect  the  new  filename. 

If  the  function  succeeds,  MS-DOS  returns  to  the  calling  program  with  the  carry  flag  clear. 
The  function  fails  if  the  new  filename  is  already  in  the  target  directory;  in  that  case, 
MS-DOS  sets  the  carry  flag  and  returns  an  error  code  in  AX. 

Example:  Change  the  name  of  the  file  MYFILE.DAT  to  MYFILE.OLD.  In  the  same  opera¬ 
tion,  move  the  file  from  the  WORK  directory  to  the  \BACKUP  directory. 


filel 

file2 


db  ’\WORK\MYFILE.DAT',0 

db  '\BACKUP\MYFILE.OLD’,0 


mov 

dx,seg  filel 

;  DS:DX  =  old  filename 

mov 

ds,  dx 

mov 

es,  dx 

mov 

dx, offset 

filel 

mov 

di, of fset 

file2 

;  ES:DI  =  new  filename 

mov 

ah,56h 

;  Function  56H  =  rename 

int 

21h 

;  transfer  to  MS-DOS 

jc 

error 

;  jump  if  rename  failed 

Deleting  a  file 

Function  41H  (Delete  File)  effectively  deletes  a  file  from  a  disk.  Before  calling  the  function, 
a  program  must  set  the  DS:DX  registers  to  point  to  the  ASCIIZ  pathname  of  the  file  to  be 
deleted.  The  supplied  pathname  cannot  specify  a  subdirectory  or  a  read-only  file,  and  the 
file  must  not  be  currently  open  by  any  process. 
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If  the  function  is  successful,  MS-DOS  deletes  the  file  by  simply  marking  the  first  byte  of  its 
directory  entry  with  a  special  character  (0E5H),  making  the  entry  subsequently  unrecog¬ 
nizable.  MS-DOS  then  updates  the  disk’s  FAT  so  that  the  clusters  that  previously  belonged 
to  the  file  are  “free”  and  returns  to  the  program  with  the  carry  flag  clear.  If  the  delete 
function  fails,  MS-DOS  sets  the  carry  flag  and  returns  an  error  code  in  AX. 

The  actual  contents  of  the  clusters  assigned  to  the  file  are  not  changed  by  a  delete  opera¬ 
tion,  so  for  security  reasons  sensitive  information  should  be  overwritten  with  spaces  or 
some  other  constant  character  before  the  file  is  deleted  with  Function  41H. 

Example:  Delete  the  file  MYFILE.DAT,  located  in  the  \WORK  directory  on  drive  C. 

fname  db  'C:  \WORK\MYFILE.DAT' , 0 


mov 

mov 

mov 

mov 

int 

jc 


dx,seg  fname 
ds,  dx 

dx, offset  fname 

ah,41h 

21h 

error 


DS:DX  =  address  of  filename 


Function  41 H  =  delete 
transfer  to  MS-DOS 
jump  if  delete  failed 


Getting/setting  file  attributes 

Function  43H  (Get/Set  File  Attributes)  obtains  or  modifies  the  attributes  of  an  existing  file. 
Before  calling  Function  43H,  the  program  must  set  the  DS:DX  registers  to  point  to  the 
ASCIIZ  pathname  for  the  file.  To  read  the  attributes,  the  program  must  set  AL  to  zero;  to  set 
the  attributes,  it  must  set  AL  to  1  and  place  an  attribute  code  in  CX.  See  Creating  a  File 
above. 


If  the  function  is  successful,  MS-DOS  reads  or  sets  the  attribute  byte  in  the  file’s  directory 
entry  and  returns  with  the  carry  flag  clear  and  the  file’s  attribute  in  CX.  If  the  function 
fails,  MS-DOS  sets  the  carry  flag  and  returns  an  error  code  in  AX. 

Function  43H  cannot  be  used  to  set  the  volume-label  bit  (bit  3)  or  the  subdirectory  bit  (bit 
4)  of  a  file.  It  also  should  not  be  used  on  a  file  that  is  currently  open  by  any  process. 


Example:  Change  the  attributes  of  the  file  MYFILE.DAT  in  the  \BACKUP  directory  on 
drive  C  to  read-only.  This  prevents  the  file  from  being  accidentally  deleted  from  the  disk. 


fname 


db  '  C :  \BACKUP  \MYF  ILE .  DAT  * ,  0 


mov  dx,seg  fname 
mov  ds ,  dx 

mov  dx, offset  fname 

mov  CX, 1 

mov  al , 1 


DS:DX  =  address  of  filename 


CX  =  attribute  (read-only) 

AL  =  mode  (0  =  get,  1  =  set) 


(more) 
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mov 

ah,43h 

;  Function  43H  =  get/set  attr 

int 

21h 

;  transfer  to  MS-DOS 

jc 

error 

;  jump  if  set  attrib.  failed 

Getting/setting  file  date  and  time 

Function  57H  (Get/Set  Date/Time  of  File)  reads  or  sets  the  directory  time  and  date  stamp 
of  an  open  file.  To  set  the  time  and  date  to  a  particular  value,  the  program  must  call  Func¬ 
tion  57H  with  the  desired  time  in  CX,  the  desired  date  in  DX,  the  handle  for  the  file  (ob¬ 
tained  from  a  previous  open  or  create  operation)  in  BX,  and  the  value  1  in  AL.  To  read  the 
time  and  date,  the  function  is  called  with  AL  containing  0  and  the  file  handle  in  BX;  the 
time  is  returned  in  the  CX  register  and  the  date  is  returned  in  the  DX  register.  As  with 
other  handle-oriented  file  functions,  if  the  function  succeeds,  the  carry  flag  is  returned 
cleared;  if  the  function  fails,  MS-DOS  returns  the  carry  flag  set  and  an  error  code  in  AX. 

The  formats  used  for  the  file  time  and  date  are  the  same  as  those  used  in  disk  directory 
entries  and  FCBs.  See  Structure  of  the  File  Control  Block  below. 

The  main  uses  of  Function  57H  are  to  force  the  time  and  date  entry  for  a  file  to  be  updated 
when  the  file  has  not  been  changed  and  to  circumvent  MS-DOS’s  modification  of  a  file 
date  and  time  when  the  file  has  been  changed.  In  the  latter  case,  a  program  can  use  this 
function  with  AL  =  0  to  obtain  the  file’s  previous  date  and  time  stamp,  modify  the  file,  and 
then  restore  the  original  file  date  and  time  by  re-calling  the  function  with  AL  =  1  before 
closing  the  file. 

Duplicating  and  redirecting  handles 

Ordinarily,  the  disk  FAT  and  directory  are  not  updated  until  a  file  is  closed,  even  when 
the  file  has  been  modified.  Thus,  until  the  file  is  closed,  any  new  data  added  to  the  file  can 
be  lost  if  the  system  crashes  or  is  turned  off  unexpectedly.  The  obvious  defense  against 
such  loss  is  simply  to  close  and  reopen  the  file  every  time  the  file  is  changed.  However, 
this  is  a  relatively  slow  procedure  and  in  a  network  environment  can  cause  the  program 
to  lose  control  of  the  file  to  another  process. 

Use  of  a  second  file  handle,  created  by  using  Function  45H  (Duplicate  File  Handle)  to 
duplicate  the  original  handle  of  the  file  to  be  updated,  can  protect  data  added  to  a  disk  file 
before  the  file  is  closed.  To  use  Function  45H,  the  program  must  put  the  handle  to  be 
duplicated  in  BX.  If  the  operation  is  successful,  MS-DOS  clears  the  carry  flag  and  returns 
the  new  handle  in  AX;  if  the  operation  fails,  MS-DOS  sets  the  carry  flag  and  returns  an 
error  code  in  AX. 

If  the  function  succeeds,  the  duplicate  handle  can  simply  be  closed  in  the  usual  manner 
with  Function  3EH.  This  forces  the  desired  update  of  the  disk  directory  and  FAT.  The  orig¬ 
inal  handle  remains  open  and  the  program  can  continue  to  use  it  for  file  read  and  write 
operations. 

Note:  While  the  second  handle  is  open,  moving  the  read/write  pointer  associated  with 
either  handle  moves  the  pointer  associated  with  the  other. 
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Example:  Assume  that  the  file  MYFILE.DAT  was  previously  opened  and  the  handle  for 
that  file  has  been  saved  in  the  variable  /handle.  Duplicate  the  handle  and  then  close  the 
duplicate  to  ensure  that  any  data  recently  written  to  the  file  is  saved  on  the  disk  and  that 
the  directory  entry  for  the  file  is  updated  accordingly. 

fhandle  dw  ?  ;  handle  from  previous  open 


;  duplicate  the  handle . . . 


mov 

bx, fhandle 

;  BX  =  handle  for  file 

mov 

ah,45h 

;  Function  45H  =  dup  handle 

int 

21h 

;  transfer  to  MS-DOS 

jc 

error 

;  jump  if  function  call  failed 

;  now  close  the  new  handle . . . 

mov 

bx,  ax 

;  BX  =  duplicated  handle 

mov 

ah,3eh 

;  Function  3EH  =  close 

int 

21h 

;  transfer  to  MS-DOS 

jc 

error 

;  jump  if  close  failed 

mov 

bx, fhandle 

;  replace  closed  handle  with  active  handle 

Function  45H  is  sometimes  also  used  in  conjunction  with  Function  46H  (Force  Duplicate 
File  Handle).  Function  46H  forces  a  handle  to  be  a  duplicate  for  another  open  handle — in 
other  words,  to  refer  to  the  same  file  or  device  at  the  same  file  read/write  pointer  location. 
The  handle  is  then  said  to  be  redirected. 

The  most  common  use  of  Function  46H  is  to  change  the  meaning  of  the  standard  input 
and  standard  output  handles  before  loading  a  child  process  with  the  EXEC  function.  In  this 
manner,  the  input  for  the  child  program  can  be  redirected  to  come  from  a  file  or  its  output 
can  be  redirected  into  a  file,  without  any  special  knowledge  on  the  part  of  the  child  pro¬ 
gram.  In  such  cases.  Function  45H  is  used  to  also  create  duplicates  of  the  standard  input 
and  standard  output  handles  before  they  are  redirected,  so  that  their  original  meanings  can 
be  restored  after  the  child  exits.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT: 
Customizing  ms-dos:  Writing  MS-DOS  Filters. 


Using  the  FCB  Functions 

A  file  control  block  is  a  data  structure,  located  in  the  application  program’s  memory  space, 
that  contains  relevant  information  about  an  open  disk  file:  the  disk  drive,  the  filename  and 
extension,  a  pointer  to  a  position  within  the  file,  and  so  on.  Each  open  file  must  have  its 
own  FCB.  The  information  in  an  FCB  is  maintained  cooperatively  by  both  MS-DOS  and  the 
application  program. 
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MS-DOS  moves  data  to  and  from  a  disk  file  associated  with  an  FCB  by  means  of  a  data 
buffer  called  the  disk  transfer  area  (DTA).  The  current  address  of  the  DTA  is  under  the 
control  of  the  application  program,  although  each  program  has  a  128-byte  default  DTA  at 
offset  80H  in  its  program  segment  prefix  (PSP).  See  PROGRAMMING  IN  THE  MS-DOS 
ENVIRONMENT:  Programming  for  ms-dos:  Structure  of  an  Application  Program. 

Under  early  versions  of  MS-DOS,  the  only  limit  on  the  number  of  files  that  can  be  open 
simultaneously  with  FCBs  is  the  amount  of  memory  available  to  the  application  to  hold  the 
FCBs  and  their  associated  disk  buffers.  However,  under  MS-DOS  versions  3.0  and  later, 
when  file-sharing  support  (SHARE.EXE)  is  loaded,  MS-DOS  places  some  restrictions  on 
the  use  of  FCBs  to  simplify  the  job  of  maintaining  network  connections  for  files.  If  the 
application  attempts  to  open  too  many  FCBs,  MS-DOS  simply  closes  the  least  recently  used 
FCBs  to  keep  the  total  number  within  a  limit. 

The  CONFIG.SYS  file  directive  FCBS  allows  the  user  to  control  the  allowed  maximum 
number  of  FCBs  and  to  specify  a  certain  number  of  FCBs  to  be  protected  against  automatic 
closure  by  the  system.  The  default  values  are  a  maximum  of  four  files  open  simultaneously 
using  FCBs  and  zero  FCBs  protected  from  automatic  closure  by  the  system.  See  USER 
COMMANDS:  CONFIG.SYS:  fcbs. 

Because  the  FCB  operations  predate  MS-DOS  version  2.0  and  because  FCBs  have  a  fixed 
structure  with  no  room  to  contain  a  path,  the  FCB  file  and  record  services  do  not  support 
the  hierarchical  directory  structure.  Many  FCB  operations  can  be  performed  only  on  files 
in  the  current  directory  of  a  disk.  For  this  reason,  the  use  of  FCB  file  and  record  operations 
should  be  avoided  in  new  programs. 

Structure  of  the  file  control  block 

Each  FCB  is  a  37-byte  array  allocated  from  its  own  memory  space  by  the  application  pro¬ 
gram  that  will  use  it.  The  FCB  contains  all  the  information  needed  to  identify  a  disk  file 
and  access  the  data  within  it:  drive  identifier,  filename,  extension,  file  size,  record  size, 
various  file  pointers,  and  date  and  time  stamps.  The  FCB  structure  is  shown  in  Table  7-3. 

Table  7-3.  Structure  of  a  Normal  File  Control  Block. 


Maintained  by 

Ofifeet 

G>ytes) 

Size 

(bytes) 

Description 

Program 

OOH 

1 

Drive  identifier 

Program 

OlH 

8 

Filename 

Program 

09H 

3 

File  extension 

MS-DOS 

OCH 

2 

Current  block  number 

Program 

OEH 

2 

Record  size  (bytes) 

MS-DOS 

lOH 

4 

File  size  (bytes) 

MS-DOS 

14H 

2 

Date  stamp 

MS-£)0S 

16H 

2 

Time  stamp 

MS-DOS 

18H 

8 

Reserved 

MS-DOS 

20H 

1 

Current  record  number 

Program 

21H 

4 

Random  record  number 
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Drive  identifier:  Initialized  by  the  application  to  designate  the  drive  on  which  the  file  to 
be  opened  or  created  resides.  0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on.  If  the 
application  supplies  a  zero  in  this  byte  (to  use  the  default  drive),  MS-DOS  alters  the  byte 
during  the  open  or  create  operation  to  reflect  the  actual  drive  used;  that  is,  after  an  open 
or  create  operation,  this  drive  will  always  contain  a  value  of  1  or  greater. 

Filename:  Standard  eight-character  filename;  initialized  by  the  application;  must  be  left 
justified  and  padded  with  blanks  if  the  name  has  fewer  than  eight  characters.  A  device 
name  (for  example,  PRN)  can  be  used;  note  that  there  is  no  colon  after  a  device  name. 

File  extension:  Three-character  file  extension;  initialized  by  the  application;  must  be  left 
justified  and  padded  with  blanks  if  the  extension  has  fewer  than  three  characters. 

Current  block  number:  Initialized  to  zero  by  MS-DOS  when  the  file  is  opened.  The  block 
number  and  the  record  number  together  make  up  the  record  pointer  during  sequential  file 
access. 

Record  size:  The  size  of  a  record  (in  bytes)  as  used  by  the  program.  MS-DOS  sets  this  field 
to  128  when  the  file  is  opened  or  created;  the  program  can  modify  the  field  afterward  to 
any  desired  record  size.  If  the  record  size  is  larger  than  128  bytes,  the  default  DTA  in  the 
PSP  cannot  be  used  because  it  will  collide  with  the  program’s  own  code  or  data. 

File  size:  The  size  of  the  file  in  bytes.  MS-DOS  initializes  this  field  from  the  file’s  directory 
entry  when  the  file  is  opened.  The  first  2  bytes  of  this  4-byte  field  are  the  least  significant 
bytes  of  the  file  size. 

Date  stamp:  The  date  of  the  last  write  operation  on  the  file.  MS-DOS  initializes  this  field 
from  the  file’s  directory  entry  when  the  file  is  opened.  This  field  uses  the  same  format 
used  by  file  handle  Function  57H  (Get/Set/Date/Time  of  File): 


Date  Format 


Bit: 

15 

14 

13 

12 

11 

10 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 

Content: 

0 

0 

0 

0 

0 

0 

0 

M 

M 

M 

M 

0 

0 

0 

0 

0 

Bits  Contents 

0-4  Day  of  month  (1-31) 

5-8  Month  (1-12) 

9-15  Year  (relative  to  1980) 

Time  stamp:  The  time  of  the  last  write  operation  on  the  file.  MS-DOS  initializes  this  field 
from  the  file’s  directory  entry  when  the  file  is  opened.  This  field  uses  the  same  format 
used  by  file  handle  Function  57H  (Get/Set/Date/Time  of  File): 
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Time  Format 


Bit: 

15 

14 

13 

12 

11 

10 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 

Content: 

0 

0 

0 

0 

0 

M 

M 

M 

M 

M 

M 

0 

0 

0 

0 

0 

Bits  Contents 

0-4  Number  of  2-second  increments  (0-29) 

5-10  Minutes  (0-59) 

11-15  Hours  (0-23) 

Current  record  number:  Together  with  the  block  number,  constitutes  the  record  pointer 
used  during  sequential  read  and  write  operations.  MS-DOS  does  not  initialize  this  field 
when  a  file  is  opened.  The  record  number  is  limited  to  the  range  0  through  127;  thus,  there 
are  128  records  per  block.  The  beginning  of  a  file  is  record  0  of  block  0. 

Random  record  pointer:  A  4-byte  field  that  identifies  the  record  to  be  transferred  by  the 
random  record  functions  21H,  22H,  27H,  and  28H.  If  the  record  size  is  64  bytes  or  larger, 
only  the  first  3  bytes  of  this  field  are  used.  MS-DOS  updates  this  field  after  random  block 
reads  and  writes  (Functions  27H  and  28H)  but  not  after  random  record  reads  and  writes 
(Functions  21H  and  22H). 

An  extended  FCB,  which  is  7  bytes  longer  than  a  normal  FCB,  can  be  used  to  access  files 
with  special  attributes  such  as  hidden,  system,  and  read-only.  The  extra  7  bytes  of  an  ex¬ 
tended  FCB  are  simply  prefixed  to  the  normal  FCB  format  (Table  7-4).  The  first  byte  of 
an  extended  FCB  always  contains  OFFH,  which  could  never  be  a  legal  drive  code  and 
therefore  serves  as  a  signal  to  MS-DOS  that  the  extended  format  is  being  used.  The  next  5 
bytes  are  reserved  and  must  be  zero,  and  the  last  byte  of  the  prefix  specifies  the  attributes 
of  the  file  being  manipulated.  The  remainder  of  an  extended  FCB  has  exactly  the  same 
layout  as  a  normal  FCB.  In  general,  an  extended  FCB  can  be  used  with  any  MS-DOS  func¬ 
tion  call  that  accepts  a  normal  FCB. 


Table  7-4.  Structure  of  an  Extended  File  Control  Block. 


Maintained  by 

Offset 

(bytes) 

Size 

(bytes) 

Description 

Program 

OOH 

1 

Extended  FCB  flag  =  OFFH 

MS-DOS 

OlH 

5 

Reserved 

Program 

06H 

1 

File  attribute  byte 

Program 

07H 

1 

Drive  identifier 

Program 

OSH 

8 

Filename 

(more) 
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Table  7-4.  Continued. 


Maintained  by 

OfEset 

(bytes) 

Size 

(bytes) 

Description 

Program 

lOH 

3 

File  extension 

MS-DOS 

13H 

2 

Current  block  number 

Program 

15H 

2 

Record  size  (bytes) 

MS-DOS 

17H 

4 

File  size  (bytes) 

MS-DOS 

IBH 

2 

Date  stamp 

MS-DOS 

IDH 

2 

Time  stamp 

MS-DOS 

IFH 

8 

Reserved 

MS-DOS 

27H 

1 

Current  record  number 

Program 

28H 

4 

Random  record  number 

Extended  FCB  flag:  When  OFFH  is  present  in  the  first  byte  of  an  FCB,  it  is  a  signal  to 
MS-DOS  that  an  extended  FCB  (44  bytes)  is  being  used  instead  of  a  normal  FCB  (37  bytes). 

File  attribute  byte:  Must  be  initialized  by  the  application  when  an  extended  FCB  is  used  to 
open  or  create  a  file.  The  bits  of  this  field  have  the  following  significance: 


Bit  Meaning 

0  Read-only 

1  Hidden 

2  System 

3  Volume  label 

4  Directory 

5  Archive 

6  Reserved 

7  Reserved 

FCB  functions  and  the  PSP 

The  PSP  contains  several  items  that  are  of  interest  when  using  the  FCB  file  and  record 
operations:  two  FCBs  called  the  default  FCBs,  the  default  DTA,  and  the  command  tail  for 
the  program.  The  following  table  shows  the  size  and  location  of  these  elements: 


PSP  Offset 

(bytes)  Size  (bytes)  Description 


5CH 

16 

Default  FCB  #1 

6CH 

20 

Default  FCB  #2 

80H 

1 

Length  of  command  tail 

81H 

127 

Command-tail  text 

80H 

128 

Default  disk  transfer  area  (DTA) 
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When  MS-DOS  loads  a  program  into  memory  for  execution,  it  copies  the  command  tail 
into  the  PSP  at  offset  81H,  places  the  length  of  the  command  tail  in  the  byte  at  offset  80H, 
and  parses  the  first  two  parameters  in  the  command  tail  into  the  default  FCBs  at  PSP 
offsets  5CH  and  6CH.  (The  command  tail  consists  of  the  command  line  used  to  invoke  the 
program  minus  the  program  name  itself  and  any  redirection  or  piping  characters  and  their 
associated  filenames  or  device  names.)  MS-DOS  then  sets  the  initial  DTA  address  for  the 
program  to  PSP:0080H. 

For  several  reasons,  the  default  FCBs  and  the  DTA  are  often  moved  to  another  location 
within  the  program’s  memory  area.  First,  the  default  DTA  allows  processing  of  only  very 
small  records.  In  addition,  the  default  FCBs  overlap  substantially,  and  the  first  byte  of  the 
default  DTA  and  the  last  byte  of  the  first  FCB  conflict.  Finally,  unless  either  the  command 
tail  or  the  DTA  is  moved  beforehand,  the  first  FCB-related  file  or  record  operation  will 
destroy  the  command  tail. 

Function  lAH  (Set  DTA  Address)  is  used  to  alter  the  DTA  address.  It  is  called  with  the 
segment  and  offset  of  the  new  buffer  to  be  used  as  the  DTA  in  DS:DX.  The  DTA  address 
remains  the  same  until  another  call  to  Function  lAH,  regardless  of  other  file  and  record 
management  calls;  it  does  not  need  to  be  reset  before  each  read  or  write. 

Note:  A  program  can  use  Function  2FH  (Get  DTA  Address)  to  obtain  the  current  DTA 
address  before  changing  it,  so  that  the  original  address  can  be  restored  later. 

Parsing  the  filename 

Before  a  file  can  be  opened  or  created  with  the  FCB  function  calls,  its  drive,  filename,  and 
extension  must  be  placed  within  the  proper  fields  of  the  FCB.  The  filename  can  be  coded 
into  the  program  itself,  or  the  program  can  obtain  it  from  the  command  tail  in  the  PSP  or 
by  prompting  the  user  and  reading  it  in  with  one  of  the  several  function  calls  for  character 
device  input. 

MS-DOS  automatically  parses  the  first  two  parameters  in  the  program’s  command  tail  into 
the  default  FCBs  at  PSP:005CH  and  PSP:006CH.  It  does  not,  however,  attempt  to  differenti¬ 
ate  between  switches  and  filenames,  so  the  pre-parsed  FCBs  are  not  necessarily  useful  to 
the  application  program.  If  the  filenames  were  preceded  by  any  switches,  the  program 
itself  has  to  extract  the  filenames  directly  from  the  command  tail.  The  program  is  then 
responsible  for  determining  which  parameters  are  switches  and  which  are  filenames,  as 
well  as  where  each  parameter  begins  and  ends. 

After  a  filename  has  been  located,  Function  29H  (Parse  Filename)  can  be  used  to  test  it 
for  invalid  characters  and  separators  and  to  insert  its  various  components  into  the  proper 
fields  in  an  FCB.  The  filename  must  be  a  string  in  the  standard  form  drive: filename. ext. 
Wildcard  characters  are  permitted  in  the  filename  and/or  extension;  asterisk  (*)  wildcards 
are  expanded  to  question  mark  (?)  wildcards. 

To  call  Function  29H,  the  DS:SI  registers  must  point  to  the  candidate  filename,  ES:DI 
must  point  to  the  37-byte  buffer  that  will  become  the  FCB  for  the  file,  and  AL  must  hold 
the  parsing  control  code.  See  SYSTEM  CALLS:  Interrupt  21h:  Function  29H. 
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If  a  drive  code  is  not  included  in  the  filename,  MS-DOS  inserts  the  drive  number  of  the 
current  drive  into  the  FCB.  Parsing  stops  at  the  first  terminator  character  encountered  in 
the  filename.  Terminators  include  the  following: 

; ,  =  +  /"[]!<>!  space  tab 

If  a  colon  character  (:)  is  not  in  the  proper  position  to  delimit  the  disk  drive  identifier  or  if 
a  period  (.)  is  not  in  the  proper  position  to  delimit  the  extension,  the  character  will  also  be 
treated  as  a  terminator.  For  example,  the  filename  CrMEMO.TXT  will  be  parsed  correctly; 
however,  ABC:DEF.DAY  will  be  parsed  as  ABC. 

If  an  invalid  drive  is  specified  in  the  filename.  Function  29H  returns  OFFH  in  AL;  if  the 
filename  contains  any  wildcard  characters,  it  returns  1.  Otherwise,  AL  contains  zero  upon 
return,  indicating  a  valid,  unambiguous  filename. 

Note  that  this  function  simply  parses  the  filename  into  the  FCB.  It  does  not  initialize  any 
other  fields  of  the  FCB  (although  it  does  zero  the  current  block  and  record  size  fields),  and 
it  does  not  test  whether  the  specified  file  actually  exists. 

Error  handling  and  FCB  functions 

The  FCB-related  file  and  record  functions  do  not  return  much  in  the  way  of  error  infor¬ 
mation  when  a  function  fails.  Typically,  an  FCB  function  returns  a  zero  in  AL  if  the  func¬ 
tion  succeeded  and  OFFH  if  the  function  failed.  Under  MS-DOS  versions  2.x,  the  program 
is  left  to  its  own  devices  to  determine  the  cause  of  the  error.  Under  MS-DOS  versions  3.x, 
however,  a  failed  FCB  function  call  can  be  followed  by  a  call  to  Interrupt  21H  Function 
59H  (pet  Extended  Error  Information).  Function  59H  will  return  the  same  descriptive 
codes  for  the  error,  including  the  error  locus  and  a  suggested  recovery  strategy,  as  would 
be  returned  for  the  counterpart  handle-oriented  file  or  record  function. 

Creating  a  file 

Function  16H  (Create  File  with  FCB)  creates  a  new  file  and  opens  it  for  subsequent  read/ 
write  operations.  The  function  is  called  with  DS:DX  pointing  to  a  valid,  unopened  FCB. 
MS-DOS  searches  the  current  directory  for  the  specifed  filename.  If  the  filename  is  found, 
MS-DOS  sets  the  file  length  to  zero  and  opens  the  file,  effectively  truncating  it  to  a  zero- 
length  file;  if  the  filename  is  not  found,  MS-DOS  creates  a  new  file  and  opens  it.  Other 
fields  of  the  FCB  are  filled  in  by  MS-DOS  as  described  below  under  Opening  a  File. 

If  the  create  operation  succeeds,  MS-DOS  returns  zero  in  AL;  if  the  operation  fails,  it 
returns  OFFH  in  AL.  This  function  will  not  ordinarily  fail  unless  the  file  is  being  created  in 
the  root  directory  and  the  directory  is  full. 

Warning:  To  avoid  loss  of  existing  data,  the  FCB  open  function  should  be  used  to  test  for 
file  existence  before  creating  a  file. 
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Opening  a  file 

Function  OFH  opens  an  existing  file.  DS:DX  must  point  to  a  valid,  unopened  FCB  contain¬ 
ing  the  name  of  the  file  to  be  opened.  If  the  specified  file  is  found  in  the  current  directory, 
MS-DOS  opens  the  file,  fills  in  the  FCB  as  shown  in  the  list  below,  and  returns  with  AL  set 
to  OOH;  if  the  file  is  not  found,  MS-DOS  returns  with  AL  set  to  OFFH,  indicating  an  error. 

When  the  file  is  opened,  MS-DOS 

•  Sets  the  drive  identifier  (offset  OOH)  to  the  actual  drive  (01  =  A,  02  =  B,  and  so  on). 

•  Sets  the  current  block  number  (offset  OCH)  to  zero. 

•  Sets  the  file  size  (offset  lOH)  to  the  value  found  in  the  directory  entry  for  the  file. 

•  Sets  the  record  size  (offset  OEH)  to  128. 

•  Sets  the  date  and  time  stamp  (offsets  14H  and  16H)  to  the  values  found  in  the  direc¬ 
tory  entry  for  the  file. 

The  program  may  need  to  adjust  the  FCB — change  the  record  size  and  the  random  record 
pointer,  for  example — before  proceeding  with  record  operations. 

Example:  Display  a  prompt  and  accept  a  filename  from  the  user.  Parse  the  filename  into 
an  FCB,  checking  for  an  illegal  drive  identifier  or  the  presence  of  wildcards.  If  a  valid, 
unambiguous  filename  has  been  entered,  attempt  to  open  the  file.  Create  the  file  if  it  does 
not  already  exist. 


kbuf 

db 

64,0,64  dup  (0) 

prompt 

db 

Odh, Oah, 'Enter  filename 

my  fob 

db 

37  dup  (0) 

mov 

;  display  the  prompt . . . 
dx,seg  prompt  ;  DS:DX  =  prompt  address 

mov 

ds,  dx 

mov 

es,  dx 

mov 

dx, offset 

prompt 

mov 

ah,09h 

;  Function  09H  =  print  string 

int 

21h 

;  transfer  to  MS-DOS 

mov 

dx, offset 

;  now  input  filename... 
kbuf  ;  DS:DX  =  buffer  address 

mov 

ah, Oah 

;  Function  OAH  =  enter  string 

int 

21h 

;  transfer  to  MS-DOS 

mov 

si, offset 

;  parse  filename  into  FCB. . . 
kbuf +2  ;  DS;SI  =  address  of  filename 

mov 

di, of fset 

myfcb  ;  ES:DI  =  address  of  fcb 

mov 

ax, 2900h 

;  Function  29H  =  parse  name 

int 

21h 

;  transfer  to  MS-DOS 

or 

al,  al 

;  jump  if  bad  drive  or 

jnz 

error 

;  wildcard  characters  in  name 

(more) 
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mov 

dx, offset 

myfcb 

/  try  to  open  file... 

;  DS:DX  =  FCB  address 

mov 

ah,0fh 

;  Function  OFH  =  open  file 

int 

21h 

;  transfer  to  MS-DOS 

or 

al,  al 

;  check  status 

jz 

proceed 

;  jump  if  open  successful 

mov 

dx, offset 

myfcb 

;  else  create  file... 

;  DS:DX  =  FCB  address 

mov 

ah, 16h 

;  Function  1 6H  =  create 

int 

21h 

;  transfer  to  MS-DOS 

or 

al,  al 

;  did  create  succeed? 

jnz 

error 

;  jump  if  create  failed 

;  file  has  been  opened  or 
;  created,  and  FCB  is  valid 
;  for  read/write  operations 

Closing  a  file 

Function  lOH  (Close  File  with  FCB)  closes  a  file  previously  opened  with  an  FCB.  As  usual, 
the  function  is  called  with  DS:DX  pointing  to  the  FCB  of  the  file  to  be  closed.  MS-DOS 
updates  the  directory,  if  necessary,  to  reflect  any  changes  in  the  file’s  size  and  the  date  and 
time  last  written. 

If  the  operation  succeeds,  MS-DOS  returns  OOH  in  AL;  if  the  operation  fails,  MS-DOS 
returns  OFFH. 

Reading  and  writing  files  with  FCBs 

MS-DOS  offers  a  choice  of  three  FCB  access  methods  for  data  within  files:  sequential, 
random  record,  and  random  block. 

Sequential  operations  step  through  the  file  one  record  at  a  time.  MS-DOS  increments  the 
current  record  and  current  block  numbers  after  each  file  access  so  that  they  point  to  the 
beginning  of  the  next  record.  This  method  is  particularly  useful  for  copying  or  listing  files. 

Random  record  access  allows  the  program  to  read  or  write  a  record  from  any  location  in 
the  file,  without  sequentially  reading  all  records  up  to  that  point  in  the  file.  The  program 
must  set  the  random  record  number  field  of  the  FCB  appropriately  before  the  read  or  write 
is  requested.  This  method  is  useful  in  database  applications,  in  which  a  program  must 
manipulate  fixed-length  records. 

Random  block  operations  combine  the  features  of  sequential  and  random  record  access 
methods.  The  program  can  set  the  record  number  to  point  to  any  record  within  a  file,  and 
MS-DOS  updates  the  record  number  after  a  read  or  write  operation.  Thus,  sequential 
operations  can  easily  be  initiated  at  any  file  location.  Random  block  operations  with  a 
record  length  of  1  byte  simulate  file-handle  access  methods. 

All  three  methods  require  that  the  FCB  for  the  file  be  open,  that  DS:DX  point  to  the  FCB, 
that  the  DTA  be  large  enough  for  the  specified  record  size,  and  that  the  DTA  address  be 
previously  set  with  Function  1  AH  if  the  default  DTA  in  the  program’s  PSP  is  not  being 
used. 
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MS-DOS  reports  the  success  or  failure  of  any  FCB-related  read  operation  (sequential, 
random  record,  or  random  block)  with  one  of  four  return  codes  in  register  AL: 


Code  Meaning 

OOH  Successful  read 

OlH  End  of  file  reached;  no  data  read  into  DTA 

02H  Segment  wrap  (DTA  too  close  to  end  of  segment);  no  data  read  into  DTA 

03H  End  of  file  reached;  partial  record  read  into  DTA 

MS-DOS  reports  the  success  or  failure  of  an  FCB-related  write  operation  as  one  of  three 
return  codes  in  register  AL: 


Code  Meaning 

OOH  Successful  write 

OlH  Disk  full;  partial  or  no  write 

02H  Segment  wrap  (DTA  too  close  to  end  of  segment);  write  failed 

For  FCB  write  operations,  records  smaller  than  one  sector  (512  bytes)  are  not  written 
directly  to  disk.  Instead,  MS-DOS  stores  the  record  in  an  internal  buffer  and  writes  the  data 
to  disk  only  when  the  internal  buffer  is  full,  when  the  file  is  closed,  or  when  a  call  to  Inter¬ 
rupt  21H  Function  ODH  (Disk  Reset)  is  issued. 

Sequential  access:  reading 

Function  14H  (Sequential  Read)  reads  records  sequentially  from  the  file  to  the  current 
DTA  address,  which  must  point  to  an  area  at  least  as  large  as  the  record  size  specified  in 
the  file’s  FCB.  After  each  read  operation,  MS-DOS  updates  the  FCB  block  and  record  num¬ 
bers  (offsets  OCH  and  20H)  to  point  to  the  next  record. 

Sequential  access:  writing 

Function  15H  (Sequential  Write)  writes  records  sequentially  from  memory  into  the  file. 

The  length  written  is  specified  by  the  record  size  field  (offset  OEH)  in  the  FCB;  the  memory 
address  of  the  record  to  be  written  is  determined  by  the  current  DTA  address.  After  each 
sequential  write  operation,  MS-DOS  updates  the  FCB  block  and  record  numbers  (offsets 
OCH  and  20H)  to  point  to  the  next  record. 

Random  record  access:  reading 

Function  21H  (Random  Read)  reads  a  specific  record  from  a  file.  Before  requesting  the 
read  operation,  the  program  specifies  the  record  to  be  transferred  by  setting  the  record 
size  and  random  record  number  fields  of  the  FCB  (offsets  OEH  and  21H).  The  current  DTA 
address  must  also  have  been  previously  set  with  Function  lAH  to  point  to  a  buffer  of 
adequate  size  if  the  default  DTA  is  not  large  enough. 
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After  the  read,  MS-DOS  sets  the  current  block  and  current  record  number  fields  (offsets 
OCH  and  20H)  to  point  to  the  same  record.  Thus,  the  program  is  set  up  to  change  to 
sequential  reads  or  writes.  However,  if  the  program  wants  to  continue  with  random  record 
access,  it  must  continue  to  update  the  random  record  field  of  the  FCB  before  each  random 
record  read  or  write  operation. 

Random  record  access:  writing 

Function  22H  (Random  Write)  writes  a  specific  record  from  memory  to  a  file.  Before 
issuing  the  function  call,  the  program  must  ensure  that  the  record  size  and  random  record 
pointer  fields  at  FCB  offsets  OEH  and  21H  are  set  appropriately  and  that  the  current  DTA 
address  points  to  the  buffer  containing  the  data  to  be  written. 

After  the  write,  MS-DOS  sets  the  current  block  and  current  record  number  fields  (offsets 
OCH  and  20H)  to  point  to  the  same  record.  Thus,  the  program  is  set  up  to  change  to 
sequential  reads  or  writes.  If  the  program  wants  to  continue  with  random  record  access,  it 
must  continue  to  update  the  random  record  field  of  the  FCB  before  each  random  record 
read  or  write  operation. 

Random  block  access:  reading 

Function  27H  (Random  Block  Read)  reads  a  block  of  consecutive  records.  Before  issuing 
the  read  request,  the  program  must  specify  the  file  location  of  the  first  record  by  setting 
the  record  size  and  random  record  number  fields  of  the  FCB  (offsets  OEH  and  21H)  and 
must  put  the  number  of  records  to  be  read  in  CX.  The  DTA  address  must  have  already  been 
set  with  Function  lAH  to  point  to  a  buffer  large  enough  to  contain  the  group  of  records  to 
be  read  if  the  default  DTA  was  not  large  enough.  The  program  can  then  issue  the  Function 
27H  call  with  DS:DX  pointing  to  the  FCB  for  the  file. 

After  the  random  block  read  operation,  MS-DOS  resets  the  FCB  random  record  pointer 
(offset  21H)  and  the  current  block  and  current  record  number  fields  (offsets  OCH  and  20H) 
to  point  to  the  beginning  of  the  next  record  not  read  and  returns  the  number  of  records 
actually  read  in  CX. 

If  the  record  size  is  set  to  1  byte.  Function  27H  reads  the  number  of  bytes  specified  in  CX, 
beginning  with  the  byte  position  specified  in  the  random  record  pointer.  This  simulates 
(to  some  extent)  the  handle  type  of  read  operation  (Function  3FH). 

Random  block  access:  writing 

Function  28H  (Random  Block  Write)  writes  a  block  of  consecutive  records  from  memory 
to  disk.  The  program  specifies  the  file  location  of  the  first  record  to  be  written  by  setting 
the  record  size  and  random  record  pointer  fields  in  the  FCB  (offsets  OEH  and  21H).  If  the 
default  DTA  is  not  being  used,  the  program  must  also  ensure  that  the  current  DTA  address 
is  set  appropriately  by  a  previous  call  to  Function  lAH.  When  Function  28H  is  called, 
DS:DX  must  point  to  the  FCB  for  the  file  and  CX  must  contain  the  number  of  records  to 
be  written. 

After  the  random  block  write  operation,  MS-DOS  resets  the  FCB  random  record  pointer 
(offset  21H)  and  the  current  block  and  current  record  number  fields  (offsets  OCH  and  20H) 
to  point  to  the  beginning  of  the  next  block  of  data  and  returns  the  number  of  records 
actually  written  in  CX. 
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If  the  record  size  is  set  to  1  byte,  Function  28H  writes  the  number  of  bytes  specified  in  CX, 
beginning  with  the  byte  position  specified  in  the  random  record  pointer.  This  simulates 
(to  some  extent)  the  handle  type  of  write  operation  (Function  40H). 

Calling  Function  28H  with  a  record  count  of  zero  in  register  CX  causes  the  file  length  to  be 
extended  or  truncated  to  the  current  value  in  the  FCB  random  record  pointer  field  (offset 
21H)  multiplied  by  the  contents  of  the  record  size  field  (offset  OEH). 

Example:  Open  the  file  MYFILE.DAT  and  create  the  file  MYFILE.BAK  on  the  current  disk 
drive,  copy  the  contents  of  the  .DAT  file  into  the  .BAK  file  using  512-byte  reads  and  writes, 
and  then  close  both  files. 


fcbl 


fcb2 


buff 


loop: 


db 

0 

drive  =  default 

db 

'MYFILE  ' 

8  character  filename 

db 

'DAT' 

3  character  extension 

db 

25  dup  (0) 

remainder  of  fcbl 

db 

0 

drive  =  default 

db 

'MYFILE  ' 

8  character  filename 

db 

'BAK' 

3  character  extension 

db 

25  dup  (0) 

remainder  of  fcb2 

db 

512  dup  (? 

) 

buffer  for  file  I/O 

• 

open  MYFILE.DAT. . . 

mov 

dx, seg  fcbl 

DSrDX  =  address  of  FCB 

mov 

ds,  dx 

mov 

dx, offset 

fcbl 

mov 

ah,0fh 

Function  OFH  =  open 

int 

21h 

transfer  to  MS-DOS 

or 

al,  al 

did  open  succeed? 

jnz 

error 

jump  if  open  failed 

create  MYFILE.BAK... 

mov 

dx, offset 

fcb2 

DS:DX  =  address  of  FCB 

mov 

ah, 1 6h 

Function  1 6H  =  create 

int 

21h 

transfer  to  MS-DOS 

or 

al,  al 

did  create  succeed? 

jnz 

error 

jump  if  create  failed 
set  record  length  to  512 

mov 

word  ptr  fcb1+0eh,512 

mov 

word  ptr  fcb2+0eh,512 

set  DTA  to  our  buffer... 

mov 

dx, offset 

buff 

DS:DX  =  buffer  address 

mov 

ah, 1  ah 

Function  1AH  =  set  DTA 

int 

21h 

transfer  to  MS-DOS 

read  MYFILE.DAT 

mov 

dx, offset 

fcbl 

DSiDX  =  FCB  address 

mov 

ah, 14h 

Function  1 4H  =  seq.  read 

int 

21h 

transfer  to  MS-DOS 

or 

al,  al 

was  read  successful? 

jnz 

done 

no,  quit 

(more) 
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mov 

dx, offset 

fcb2 

mov 

ah, 15h 

int 

21h 

or 

al,  al 

jnz 

error 

jmp 

loop 

mov 

dx, offset 

fcbl 

mov 

ah, lOh 

int 

21h 

or 

al,  al 

jnz 

error 

mov 

dx, offset 

fcb2 

mov 

ah, lOh 

int 

21h 

or 

al,  al 

jnz 

error 

DS:DX  =  FCB  address 
Function  1 5H  =  seq.  write 
transfer  to  MS-DOS 
was  write  successful? 
jump  if  write  failed 
continue  to  end  of  file 
now  close  files... 

DS:DX  =  FCB  for  MYFILE.DAT 
Function  10H  =  close  file 
transfer  to  MS-DOS 
did  close  succeed? 
jump  if  close  failed 
DSrDX  =  FCB  for  MYFILE.BAK 
Function  10H  =  close  file 
transfer  to  MS-DOS 
did  close  succeed? 
jump  if  close  failed 


Other  FCB  file  operations 

As  it  does  with  file  handles,  MS-DOS  provides  FCB-oriented  functions  to  rename  or  delete 
a  file.  Unlike  the  other  FCB  functions  and  their  handle  counterparts,  these  two  functions 
accept  wildcard  characters.  An  additional  FCB  function  allows  the  size  or  existence  of  a 
file  to  be  determined  without  actually  opening  the  file. 

Renaming  a  file 

Function  17H  (Rename  File)  renames  a  file  (or  files)  in  the  current  directory.  The  file  to  be 
renamed  cannot  have  the  hidden  or  system  attribute.  Before  calling  Function  17H,  the  pro¬ 
gram  must  create  a  special  FCB  that  contains  the  drive  code  at  offset  OOH,  the  old  filename 
at  offset  OlH,  and  the  new  filename  at  offset  IIH.  Both  the  current  and  the  new  filenames 
can  contain  the  ?  wildcard  character. 

When  the  function  call  is  made,  DS:DX  must  point  to  the  special  FCB  structure.  MS-DOS 
searches  the  current  directory  for  the  old  filename.  If  it  finds  the  old  filename,  MS-DOS 
then  searches  for  the  new  filename  and,  if  it  finds  no  matching  filename,  changes  the 
directory  entry  for  the  old  filename  to  reflect  the  new  filename.  If  the  old  filename  field  of 
the  special  FCB  contains  any  wildcard  characters,  MS-DOS  renames  every  matching  file. 
Duplicate  filenames  are  not  permitted;  the  process  will  fail  at  the  first  duplicate  name. 

If  the  operation  is  successful,  MS-DOS  returns  zero  in  AL;  if  the  operation  fails,  it  returns 
OFFH.  The  error  condition  may  indicate  either  that  no  files  were  renamed  or  that  at  least 
one  file  was  renamed  but  the  operation  was  then  terminated  because  of  a  duplicate 
filename. 

Example:  Rename  all  the  files  with  the  extension  .ASM  in  the  current  directory  of  the 
default  disk  drive  to  have  the  extension  .COD. 
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db 

0 

;  default  drive 

db 

» 9  9  9  » 

;  wildcard  filename 

db 

'ASM' 

;  old  extension 

db 

5  dup  (0) 

;  reserved  area 

db 

, 99999999 , 

;  wildcard  filename 

db 

'COD' 

;  new  extension 

db 

1 5  dup  ( 0 ) 

;  remainder  of  FCB 

mov 

dx,seg  renfcb  ; 

DS:DX  =  address  of 

mov 

ds , dx  ; 

"special"  FCB 

mov 

dx, offset  renfcb 

mov 

ah,17h 

Function  17H  =  rename 

int 

21h 

transfer  to  MS-DOS 

or 

al,al  ; 

did  function  succeed? 

jnz 

error  ; 

jump  if  rename  failed 

Deleting  a  file 

Function  13H  (Delete  File)  deletes  a  file  from  the  current  directory.  The  file  should  not  be 
currently  open  by  any  process.  If  the  file  to  be  deleted  has  special  attributes,  such  as  read¬ 
only,  the  program  must  use  an  extended  FCB  to  remove  the  file.  Directories  cannot  be 
deleted  with  this  function,  even  with  an  extended  FCB. 

Function  13H  is  called  with  DS:DX  pointing  to  an  unopened,  valid  FCB  containing  the 
name  of  the  file  to  be  deleted.  The  filename  can  contain  the  ?  wildcard  character;  if  it  does, 
MS-DOS  deletes  all  files  matching  the  specified  name.  If  at  least  one  file  matches  the  FCB 
and  is  deleted,  MS-DOS  returns  OOH  in  AL;  if  no  matching  filename  is  found,  it  returns 
OFFH. 

Note:  This  function,  if  it  succeeds,  does  not  return  any  information  about  which  and 
how  many  files  were  deleted.  When  multiple  files  must  be  deleted,  closer  control  can  be 
exercised  by  using  the  Find  File  functions  (Functions  IIH  and  12H)  to  inspect  candidate 
filenames.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for 
MS-DOS:  Disk  Directories  and  Volume  Labels.  The  files  can  then  be  deleted  individually. 

Example:  Delete  all  the  files  in  the  current  directory  of  the  current  disk  drive  that  have 
the  extension  .BAK  and  whose  filenames  have  A  as  the  first  character. 


db 

0 

;  default  drive 

db 

' A??????? ' 

;  wildcard  filename 

db 

'BAK' 

;  extension 

db 

25  dup  (0) 

;  remainder  of  FCB 

(more) 
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mov 

dx,seg  delfcb 

mov 

ds,  dx 

mov 

dx, offset  delfcb 

mov 

ah,13h 

int 

21h 

or 

al,al 

jnz 

error 

DS:DX  =  FCB  address 


Function  1 3H  =  delete 
transfer  to  MS-DOS 
did  function  succeed? 
jump  if  delete  failed 


Finding  file  size  and  testing  for  existence 

Function  23H  (Get  File  Size)  is  used  primarily  to  find  the  size  of  a  disk  file  without  opening 
it,  but  it  may  also  be  used  instead  of  Function  IIH  (Find  First  File)  to  simply  test  for  the 
existence  of  a  file.  Before  calling  Function  23H,  the  program  must  parse  the  filename  into 
an  unopened  FCB,  initialize  the  record  size  field  of  the  FCB  (offset  OEH),  and  set  the 
DS:DX  registers  to  point  to  the  FCB. 

When  Function  23H  returns,  AL  contains  OOH  if  the  file  was  found  in  the  current  directory 
of  the  specified  drive  and  OFFH  if  the  file  was  not  found. 

If  the  file  was  found,  the  random  record  field  at  FCB  offset  21H  contains  the  number  of 
records  (rounded  upward)  in  the  target  file,  in  terms  of  the  value  in  the  record  size  field 
(offset  OEH)  of  the  FCB.  If  the  record  size  is  at  least  64  bytes,  only  the  first  3  bytes  of  the 
random  record  field  are  used;  if  the  record  size  is  less  than  64  bytes,  all  4  bytes  are  used.  To 
obtain  the  size  of  the  file  in  bytes,  the  program  must  set  the  record  size  field  to  1  before  the 
call.  This  method  is  not  any  faster  than  simply  opening  the  file,  but  it  does  avoid  the  over¬ 
head  of  closing  the  file  afterward  (which  is  necessary  in  a  networking  environment). 


Summary 

MS-DOS  supports  two  distinct  but  overlapping  sets  of  file  and  record  management 
services.  The  handle-oriented  functions  operate  in  terms  of  null-terminated  (ASCIIZ) 
filenames  and  l6-bit  file  identifiers,  called  handles,  that  are  returned  by  MS-DOS  after  a  file 
is  opened  or  created.  The  filenames  can  include  a  full  path  specifying  the  file’s  location  in 
the  hierarchical  directory  structure.  The  information  associated  with  a  file  handle,  such  as 
the  current  read/write  pointer  for  the  file,  the  date  and  time  of  the  last  write  to  the  file,  and 
the  file’s  read/write  permissions,  sharing  mode,  and  attributes,  is  maintained  in  a  table 
internal  to  MS-DOS. 
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In  contrast,  the  FCB-oriented  functions  use  a  37-byte  structure  called  a  file  control  block, 
located  in  the  application  program’s  memory  space,  to  specify  the  name  and  location  of 
the  file.  After  a  file  is  opened  or  created,  the  FCB  is  used  by  both  MS-DOS  and  the  applica¬ 
tion  to  hold  other  information  about  the  file,  such  as  the  current  read/write  file  pointer, 
while  that  file  is  in  use.  Because  FCBs  predate  the  hierarchical  directory  structure  that  was 
introduced  in  MS-DOS  version  2.0  and  do  not  have  room  to  hold  the  path  for  a  file,  the  FCB 
functions  cannot  be  used  to  access  files  that  are  not  in  the  current  directory  of  the  speci¬ 
fied  drive. 

In  addition  to  their  lack  of  support  for  pathnames,  the  FCB  functions  have  much  poorer 
error  reporting  capabilities  than  handle  functions  and  are  nearly  useless  in  networking 
environments  because  they  do  not  support  file  sharing  and  locking.  Consequently,  it  is 
strongly  recommended  that  the  handle-related  file  and  record  functions  be  used  ex¬ 
clusively  in  all  new  applications. 


Robert  Byers 
Code  by  Ray  Duncan 
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Article  8 

Disk  Directories  and  Volume  Labels 


MS-DOS,  being  a  disk  operating  system,  provides  facilities  for  cataloging  disk  files.  The 
data  structure  used  by  MS-DOS  for  this  purpose  is  the  directory,  a  linear  list  of  names  in 
which  each  name  is  associated  with  a  physical  location  on  the  disk.  Directories  are  ac¬ 
cessed  and  updated  implicitly  whenever  files  are  manipulated,  but  both  directories  and 
their  contents  can  also  be  manipulated  explicitly  using  several  of  the  MS-DOS  Interrupt 
21H  service  functions. 

MS-DOS  versions  1.x  support  only  one  directory  on  each  disk.  Versions  2.0  and  later, 
however,  support  multiple  directories  linked  in  a  two-way,  hierarchical  tree  structure 
(Figure  8-1),  and  the  complete  specification  of  the  name  of  a  file  or  directory  thus  must 
describe  the  location  in  the  directory  hierarchy  in  which  the  name  appears.  This  specifica¬ 
tion,  or  path,  is  created  by  concatenating  a  disk  drive  specifier  (for  example.  A:  or  C:),  the 


C:\  (root  directory) 


subdirectory 

ALPHA 

subdirectory 

BETA 

file 

FE.E1.COM 

file 

FILE2.COM 

C:\ALPHA 


subdirectory 

• 

subdirectory 

•  • 

subdirectory 

GAMMA 

subdirectory 

DELTA 

file 

FILE3.COM 

I - 1 

C:\ALPHA\GAMMA  C:\ALPHA\DELTA 


subdirectory  • 

■ 

subdirectory  • 

subdirectory  •  • 

subdirectory  •  • 

file  FILE5.COM 

1 

C:\BETA 


subdirectory 

subdirectory 

subdirectory 

file 

• 

•  • 

EPSILON 

ITLE4.COM 

C:\BETAN 

EPSILON 

subdirectory 

• 

subdirectory 

•  • 

file 

FILE1.COM 

Figure  8-1.  Typical  hierarchical  directory  structure  (MS-DOS  versions  2.0  and  later). 
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names  of  the  directories  in  hierarchical  order  starting  with  the  root  directory,  and  finally 
the  name  of  the  file  or  directory.  For  example,  in  Figure  8-1,  the  complete  pathname  for 
FILE5.COM  is  C:\ALPHA\GAMMA\FILE5.COM.  The  two  instances  ofFILEl.COM,  in  the 
root  directory  and  in  the  directory  EPSILON,  are  distinguished  by  their  pathnames: 
C:\FILEl.COM  in  the  first  instance  and  C:\BETA\EPSILON\FILEl.COM  in  the  second. 

Note:  If  no  drive  is  specified,  the  current  drive  is  assumed.  Also,  if  the  first  name  in  the 
specification  is  not  preceded  by  a  backslash,  the  specification  is  assumed  to  be  relative  to 
the  current  directory.  For  example,  if  the  current  directory  is  C:\BETA\EPSILON,  the 
specification  \  FILE1.COM  indicates  the  file  FILE1.COM  in  the  root  directory  and  the 
specification  FILE1.COM  indicates  the  file  FILE1.COM  in  the  directory  C:\BETA\EPSILON. 
See  Figure  8-1. 

Although  the  casual  user  of  MS-DOS  need  not  be  concerned  with  how  this  hierarchical 
directory  structure  is  implemented,  MS-DOS  programmers  should  be  familiar  with  the 
internal  structure  of  directories  and  with  the  Interrupt  21H  functions  available  for  manip¬ 
ulating  directory  contents  and  maintaining  the  links  between  directories.  This  article 
provides  that  information. 


Logical  Structure  of  MS-DOS  Directories 

An  MS-DOS  directory  consists  of  a  list  of  32-byte  directory  entries,  each  of  which  con¬ 
tains  a  name  and  descriptive  information.  In  MS-DOS  versions  1.x,  each  name  must  be  a 
filename;  in  versions  2.0  and  later,  volume  labels  and  directory  names  can  also  appear 
in  directory  entries. 

Directory  searches 

Directory  entries  are  not  sorted,  nor  are  they  maintained  as  a  linked  list.  Thus,  when 
MS-DOS  searches  a  directory  for  a  name,  the  search  must  proceed  linearly  from  the  first 
name  in  the  directory.  In  MS-DOS  versions  1.x,  a  directory  search  continues  until  the  spec¬ 
ified  name  is  found  or  until  every  entry  in  the  directory  has  been  examined.  In  versions  2.0 
and  later,  the  search  continues  until  the  specified  name  is  found  or  until  a  null  directory 
entry  (that  is,  one  whose  first  byte  is  zero)  is  encountered.  This  null  entry  indicates  the 
logical  end  of  the  directory. 

Adding  and  deleting  directory  entries 

MS-DOS  deletes  a  directory  entry  by  marking  it  with  0E5H  in  the  first  byte  rather  than  by 
erasing  it  or  excising  it  from  the  directory.  New  names  are  added  to  the  directory  by  reus¬ 
ing  the  first  deleted  entry  in  the  list.  If  no  deleted  entries  are  available,  MS-DOS  appends 
the  new  entry  to  the  list. 
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The  cuirent  directory 

when  more  than  one  directory  exists  on  a  disk,  MS-DOS  keeps  track  of  a  default  search 
directory  known  as  the  current  directory.  The  current  directory  is  the  directory  used  for  all 
implicit  directory  searches,  such  as  those  occasioned  by  a  request  to  open  a  file,  if  no  alter¬ 
native  path  is  specified.  At  startup,  MS-DOS  makes  the  root  directory  the  current  directory, 
but  any  other  directory  can  be  designated  later,  either  interactively  by  using  the  CHDIR 
command  or  from  within  an  application  by  using  Interrupt  21H  Function  3BH  (Change 
Current  Directory). 


Directory  Format 

The  root  directory  is  created  by  the  MS-DOS  FORMAT  program.  See  USER  COMMANDS: 
FORMAT.  The  FORMAT  program  places  the  root  directory  immediately  after  the  disk’s  file 
allocation  tables  (FATs).  FORMAT  also  determines  the  size  of  the  root  directory.  The  size 
depends  on  the  capacity  of  the  storage  medium:  FORMAT  places  larger  root  directories  on 
high-capacity  fixed  disks  and  smaller  root  directories  on  floppy  disks.  In  contrast,  the  size 
of  subdirectories  is  limited  only  by  the  storage  capacity  of  the  disk  because  disk  space  for 
subdirectories  is  allocated  dynamically,  as  it  is  for  any  MS-DOS  file.  The  size  and  physical 
location  of  the  root  directory  can  be  derived  from  data  in  the  BIOS  parameter  block  (BPB) 
in  the  disk  boot  sector.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Struc¬ 
ture  OF  MS-DOS:  MS-DOS  Storage  Devices. 

Because  space  for  the  root  directory  is  allocated  only  when  the  disk  is  formatted,  the 
root  directory  cannot  be  deleted  or  moved.  Subdirectories,  whose  disk  space  is  allocated 
dynamically,  can  be  added  or  deleted  as  needed. 

Directory  entry  format 

Each  32-byte  directory  entry  consists  of  seven  fields,  including  a  name,  an  attribute  byte, 
date  and  time  stamps,  and  information  that  describes  the  file’s  size  and  physical  location 
on  the  disk  (Figure  8-2).  The  fields  are  formatted  as  described  in  the  following  paragraphs. 


0 

OBH 

OCH 

16H 

18H 

lAH 

ICH  IFH 

Name 

Attribute 

(Reserved) 

Time 

Date 

Starting  cluster 

File  size 

Figure  8-2.  Format  of  a  directory  entry. 

The  name  field  (bytes  O-OAH)  contains  an  11-byte  name  unless  the  first  byte  of  the  field 
indicates  that  the  directory  entry  is  deleted  or  null.  The  name  can  be  an  11-byte  filename 
(8-byte  name  followed  by  a  3-byte  extension),  an  11-byte  subdirectory  name  (8-byte  name 
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followed  by  a  3-byte  extension),  or  an  11-byte  volume  label.  Names  less  than  8  bytes  and 
extensions  less  than  3  bytes  are  padded  to  the  right  with  blanks  so  that  the  extension  al¬ 
ways  appears  in  bytes  08-0AH  of  the  name  field.  The  first  byte  of  the  name  field  can  con¬ 
tain  certain  reserved  values  that  affect  the  way  MS-DOS  processes  the  directory  entry: 


Value  Meaning 

0  Null  directory  entry  (logical  end  of  directory  in  MS-DOS  versions  2.0  and  later) 

5  First  character  of  name  to  be  displayed  as  the  character  represented  by  0E5H 

(MS-DOS  version  3.2  ) 

0E5H  Deleted  directory  entry 

When  MS-DOS  creates  a  subdirectory,  it  always  includes  two  aliases  as  the  first  two  entries 
in  the  newly  created  directory.  The  name .  (an  ASCII  period)  is  an  alias  for  the  name  of 
the  current  directory;  the  name ..  (two  ASCII  periods)  is  an  alias  for  the  directory’s  parent 
directory — that  is,  the  directory  in  which  the  entry  containing  the  name  of  the  current 
directory  is  found. 

The  attribute  field  (byte  OBH)  is  an  8-bit  field  that  describes  the  way  MS-DOS  processes 
the  directory  entry  (Figure  8-3).  Each  bit  in  the  attribute  field  designates  a  particular  attri¬ 
bute  of  that  directory  entry;  more  than  one  of  the  bits  can  be  set  at  a  time. 


1 

6 

5 

4 

3 

2 

1 

0 

(Reserved) 

(Reserved) 

Archive 

Sub¬ 

directory 

Volume 

label 

System  file 

Hidden  file 

Read-only 

file 

Figure  8-3.  Format  of  the  attribute field  in  a  directory  entry. 

The  read-only  bit  (bit  0)  is  set  to  1  to  mark  a  file  read-only.  Interrupt  21H  Function  3DH 
(Open  File  with  Handle)  will  fail  if  it  is  used  in  an  attempt  to  open  this  file  for  writing.  The 
hidden  bit  (bit  1)  is  set  to  1  to  indicate  that  the  entry  is  to  be  skipped  in  normal  directory 
searches — that  is,  in  directory  searches  that  do  not  specifically  request  that  hidden  entries 
be  included  in  the  search.  The  system  bit  (bit  2)  is  set  to  1  to  indicate  that  the  entry  refers  to 
a  file  used  by  the  operating  system.  Like  the  hidden  bit,  the  system  bit  excludes  a  directory 
entry  from  normal  directory  searches.  The  volume  label  bit  (bit  3)  is  set  to  1  to  indicate  that 
the  directory  entry  represents  a  volume  label.  The  subdirectory  bit  (bit  4)  is  set  to  1  when 
the  directory  entry  contains  the  name  and  location  of  another  directory.  This  bit  is  always 
set  for  the  directory  entries  that  correspond  to  the  current  directory  (.)  and  the  parent 
directory  (..).  The  archive  bit  (bit  5)  is  set  to  1  by  MS-DOS  functions  that  close  a  file  that 
has  been  written  to.  Simply  openihg  and  closing  a  file  is  not  sufficient  to  update  the 
archive  bit  in  the  file’s  directory  entry. 

The  time  and  date  fields  (bytes  16-17H  and  18-19H)  are  initialized  by  MS-DOS  when 
the  directory  entry  is  created.  These  fields  are  updated  whenever  a  file  is  written  to.  The 
formats  of  these  fields  are  shown  in  Figures  8-4  and  8-5. 
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Bit 

15 

10 

4  0 

Hours  (0-23) 

Minutes  (0-59) 

2-second 
increments  (0-29) 

Figure  8-4.  Format  of  the  time field  in  a  directory  entry. 

Bit 

15 

8 

4  0 

Year  (relative  to  1980) 

Month  (1-12) 

Day  (1-31) 

Figure  8-5.  Format  of  the  date  field  in  a  directory  entry. 

The  starting  cluster  field  (bytes  lA-lBH)  indicates  the  disk  location  of  the  first  cluster 
assigned  to  the  file.  This  cluster  number  can  be  used  as  an  entry  point  to  the  file  allocation 
table  (FAT)  for  the  disk.  (Cluster  numbers  can  be  converted  to  logical  sector  numbers  with 
the  aid  of  the  information  in  the  disk’s  BPB.) 

For  the .  entry  (the  alias  for  the  directory  that  contains  the  entry),  the  starting  cluster  field 
contains  the  starting  cluster  number  of  the  directory  itself.  For  the ..  entry  (the  alias  for  the 
parent  directory),  the  value  in  the  starting  cluster  field  refers  to  the  parent  directory  unless 
the  parent  directory  is  the  root  directory,  in  which  case  the  starting  cluster  number  is  zero. 

The  file  size  field  (bytes  IC-IFH)  is  a  32-bit  integer  that  indicates  the  file  size  in  bytes. 


Volume  Labels 

The  generic  term  volume  refers  to  a  unit  of  auxiliary  storage  such  as  a  floppy  disk,  a  fixed 
disk,  or  a  reel  of  magnetic  tape.  In  computer  environments  where  many  different  volumes 
might  be  used,  the  operating  system  can  uniquely  identify  each  volume  by  initializing  it 
with  a  volume  label. 

Volume  labels  are  implemented  in  MS-DOS  versions  2.0  and  later  as  a  specific  type  of 
directory  entry  specified  by  setting  bit  3  in  the  attribute  field  to  1.  In  a  volume  label  direc¬ 
tory  entry,  the  name  field  contains  an  11-byte  string  specifying  a  name  for  the  disk  volume. 
A  volume  label  can  appear  only  in  the  root  directory  of  a  disk,  and  only  one  volume  label 
can  be  present  on  any  given  disk. 

In  MS-DOS  versions  2.0  and  later,  the  FORMAT  command  can  be  used  with  the  /V  switch 
to  initialize  a  disk  with  a  volume  label.  In  versions  3.0  and  later,  the  LABEL  command  can 
be  used  to  create,  update,  or  delete  a  volume  label.  Several  commands  can  display  a  disk’s 
volume  label,  including  VOL,  DIR,  LABEL,  TREE,  and  CHKDSK.  See  USER  COMMANDS. 
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In  MS-DOS  versions  2.x,  volume  labels  are  simply  a  convenience  for  the  user;  no  MS-DOS 
routine  uses  a  volume  label  for  any  other  purpose.  In  MS-DOS  versions  3.x,  however,  the 
SHARE  command  examines  a  disk’s  volume  label  when  it  attempts  to  verify  whether  a 
disk  volume  has  been  inadvertently  replaced  in  the  midst  of  a  file  read  or  write  operation. 
Removable  disk  volumes  should  therefore  be  assigned  unique  volume  names  if  they  are 
to  contain  shared  files. 


Functional  Support  for  MS-DOS  Directories 

Several  Interrupt  21H  service  routines  can  be  useful  to  programmers  who  need  to  manipu¬ 
late  directories  and  their  contents  (Table  8-1).  The  routines  can  be  broadly  grouped  into 
two  categories:  those  that  use  a  modified  file  control  block  (FCB)  to  pass  filenames  to  and 
from  the  Interrupt  21H  service  routines  (Functions  IIH,  12H,  17H,  and  23H)  and  those  that 
use  hierarchical  path  specifications  (Functions  39H,  3AH,  3BH,  43H,  47H,  4EH,  4FH,  56H, 
and  57H).  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for 
MS-DOS:  File  and  Record  Management;  SYSTEM  CALLS:  Interrupt  21h. 

The  functions  that  use  an  FCB  require  that  the  calling  program  reserve  enough  memory 
for  an  extended  FCB  before  the  Interrupt  21H  function  is  called.  The  calling  program  ini¬ 
tializes  the  filename  and  extension  fields  of  the  FCB  and  passes  the  address  of  the  FCB  to 
the  MS-DOS  service  routine  in  DS:DX.  The  functions  that  use  pathnames  expect  all  path¬ 
names  to  be  in  ASCIIZ  format — that  is,  the  last  character  of  the  name  must  be  followed 
by  a  zero  byte. 

Names  in  pathnames  passed  to  Interrupt  21H  functions  can  be  separated  by  either  a  back¬ 
slash  (\)  or  a  forward  slash  (/).  (The  forward  slash  is  the  separator  character  used  in  path¬ 
names  in  UNIX/XENIX  systems.)  For  example,  the  pathnames  C:/MSP/SOURCE/ROSE.PAS 
and  C:\MSP\SOURCE\ROSE.PAS  are  equivalent  when  passed  to  an  Interrupt  2IH  function. 
The  forward  slash  can  thus  be  used  in  a  pathname  in  a  program  that  must  run  on  both  MS- 
DOS  and  UNIX/XENIX.  However,  the  MS-DOS  comand  processor  (COMMAND.COM) 
recognizes  only  the  backslash  as  a  pathname  separator  character,  so  forward  slashes  can¬ 
not  be  used  as  separators  in  the  command  line. 


Table  8-1.  MS-DOS  Functions  for  Accessing  Directories. 


Function 

CaUWith 

Returns 

Comment 

Find  First  File 

AH=11H 

AL  =  0  (directory  entry 

If  default  not  satisfac¬ 

DS:DX  =  pointer  to 

found)  or  OFFH  (not  found) 

tory,  DTA  must  be 

unopened  FCB 

DTA  updated  (if  directory 

set  before  using 

INT21H 

entry  found) 

this  function. 

Find  Next  File 

AH  =  12H 

AL  =  0  (directory  entry 

Use  the  same  FCB 

DS:DX  =  pointer  to 

found)  or  OFFH  (not  found) 

for  Function  IIH  and 

unopened  FCB 
INT21H 

DTA  updated  (if  directory 
entry  found) 

Function  12H. 

(more) 
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Table  8-1.  Continued. 


Function 

CaUXUth 

Returns 

Rename  File 

AH=17H 

DS:DX  =  pointer  to 
modified  FCB 

INT21H 

AL  =  0  (file  renamed)  or 

OFFH  (no  directory  entry 
or  duplicate  filename) 

Get  File  Size 

AH  =  23H 

DS:DX  =  pointer  to 
unopened  FCB 

INT21H 

AL  =  0  (directory  entry 
found)  or  OFFH  (not  found) 
FCB  updated  with  number 
of  records  in  file 

Create  Directory 

AH  =  39H 

DS:DX  =  pointer  to 

ASCIIZ  pathname 
INT21H 

Carry  flag  set  (if  error) 

AX  =  error  code  (if  error) 

Remove  Directory 

AH  =  3AH 

DS:DX  =  pointer  to 

ASCIIZ  pathname 
INT21H 

Carry  flag  set  (if  error) 

AX  =  error  code  (if  error) 

Change  Current 
Directory 

AH  =  3BH 

DS:DX  =  pointer  to 

ASCIIZ  pathname 
INT21H 

Carry  flag  set  (if  error) 

AX  =  error  code  (if  error) 

Get/Set  File 
Attributes 

AH  =  43H 

AL  =  0  (get  attributes) 

1  (set  attributes) 

CX  =  attributes  (if  AL  =  1) 
DS:DX  =  pointer  to 

ASCIIZ  pathname 

INT  21H 

Carry  flag  set  (if  error) 

AX  =  error  code  (if  error) 

CX  =  attribute  field  from 
directory  entry  (if  called 
with  AL  =  0) 

Get  Current 
Directory 

AH  =  47H 

DS:SI  =  pointer  to 

64-byte  buffer 

DL  =  drive  number 
INT21H 

Carry  flag  set  (if  error) 

AX  =  error  code  (if  error) 
Buffer  updated  with 
pathname  of  current 
directory 

Find  First  File 

AH  =  4EH 

DS:DX  =  pointer  to 

ASCIIZ  pathname 

CX.  =  file  attributes  to 
match 

INT21H 

Carry  flag  set  (if  error) 

AX  =  error  code  (if  error) 
DTA  updated 

Find  Next  File 

AH  =  4FH 

INT21H 

Carry  flag  set  (if  error) 

AX  =  error  code  (if  error) 
DTA  updated 

Comment 


Cannot  be  used  to 
modify  the  volume 
label  or  subdirectory 
bits. 


If  default  not  satisfac¬ 
tory,  DTA  must  be 
set  before  using 
this  function. 


(more) 
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Table  8-1.  Continued. 


Function 

Call^dth 

Returns 

Comment 

Rename  File 

AH  =  56H 

DS:DX  =  pointer  to 

ASCIIZ  pathname 

ES:DI  =  pointer  to 
new  ASCIIZ  pathname 
INT  21H 

Carry  flag  set  (if  error) 

AX  =  error  code  (if  error) 

Get/Set  Date/Time 
of  File 

AH  =  57H 

AL  =  0  (get  date/time) 

1  (set  date/time) 

BX  =  handle 

CX  =  time(ifAL=l) 

DX  =  date(ifAL=l) 
INT21H 

Carry  flag  set  (if  error) 

AX  =  error  code  (if  error) 

CX  =  time(ifAL  =  0) 
DX=date(ifAL  =  0) 

Searching  a  directory 

Two  pairs  of  Interrupt  21H  functions  are  available  for  directory  searches.  Functions  IIH 
and  12H  use  FCBs  to  transfer  filenames  to  MS-DOS;  these  functions  are  available  in  all  ver¬ 
sions  of  MS-DOS,  but  they  cannot  be  used  with  pathnames.  Functions  4EH  and  4FH  sup¬ 
port  pathnames,  but  these  functions  are  unavailable  in  MS-DOS  versions  1.x.  All  four 
functions  require  the  address  of  the  disk  transfer  area  (DTA)  to  be  initialized  appropriately 
before  the  function  is  invoked.  When  Function  12H  or  4FH  is  used,  the  current  DTA  must 
be  the  same  as  the  DTA  for  the  preceding  call  to  Function  IIH  or  4EH. 

The  Interrupt  21H  directory  search  functions  are  designed  to  be  used  in  pairs.  The  Find 
First  File  functions  return  the  first  matching  directory  entry  in  the  current  directory  (Func¬ 
tion  IIH)  or  in  the  specified  directory  (Function  4EH).  The  Find  Next  File  functions 
(Functions  12H  and  4FH)  can  be  called  repeatedly  after  a  successful  call  to  the  corre¬ 
sponding  Find  First  File  function.  Each  call  to  one  of  the  Find  Next  File  functions  returns 
the  next  directory  entry  that  matches  the  name  originally  specified  to  the  Find  First  File 
function.  A  directory  search  can  thus  be  summarized  as  follows: 

call  "find  first  file"  function 

while  (  matching  directory  entry  returned  ) 
call  "find  next  file"  function 

Wildcard  characters 

This  search  strategy  is  used  because  name  specifications  can  include  the  wildcard  charac¬ 
ters  ?,  which  matches  any  single  character,  and  ♦  {.see  below).  When  one  or  more  wildcard 
characters  appear  in  the  name  specified  to  one  of  the  Find  First  File  functions,  only  the 
nonwildcard  characters  in  the  name  participate  in  the  directory  search.  Thus,  for  example, 
the  specification  FOO?  matches  the  filenames  FOOl,  F002,  and  so  on;  the  specification 
FOO?????.???  matches  F004.COM,  FOOBAR.EXE,  and  FOONEW.BAK,  as  well  as  FOOl  and 
F002;  the  specification  ????????.TXT  matches  all  files  whose  extension  is  .TXT;  the  speci¬ 
fication  ????????.???  matches  all  files  in  the  directory. 
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Function  4EH  also  recognizes  the  wildcard  character  *,  which  matches  any  remaining 
characters  in  a  filename  or  extension.  MS-DOS  expands  the  *  wildcard  character  inter¬ 
nally  to  question  marks.  Thus,  for  example,  the  specification  FOO  ♦  is  the  same  as 
FOO?????;  the  specification  FOO  ♦.♦  is  the  same  as  FOO?????.???;  and,  of  course,  the  spec¬ 
ification  is  the  same  as  ????????.???. 

Examining  a  directory  entry 

All  four  Interrupt  21H  directory  search  functions  return  the  name,  attribute,  file  size,  time, 
and  date  fields  for  each  directory  entry  found  during  a  directory  search.  The  current  DTA 
is  used  to  return  this  data,  although  the  format  is  different  for  the  two  pairs  of  functions: 
Functions  IIH  and  12H  return  a  copy  of  the  32-byte  directory  entry — including  the  cluster 
number — in  the  DTA;  Functions  4EH  and  4FH  return  a  43-byte  data  structure  that  does 
not  include  the  starting  cluster  number.  See  SYSTEM  CALLS:  Interrupt  21h:  Function 
4EH. 

The  attribute  field  of  a  directory  entry  can  be  examined  using  Function  43H  (Get/Set  File 
Attributes).  Also,  Function  57H  (Get/Set  Date/Time  of  File)  can  be  used  to  examine  a  file’s 
time  or  date.  However,  unlike  the  other  functions  discussed  here.  Function  57H  is  in¬ 
tended  only  for  files  that  are  being  actively  used  within  an  application — that  is.  Function 
57H  can  be  called  to  examine  the  file’s  time  or  date  stamp  only  after  the  file  has  been 
opened  or  created  using  an  Interrupt  21H  function  that  returns  a  handle  (Function  3CH, 
3DH,5AH,or5BH). 

Modifying  a  directory  entry 

Four  Interrupt  21H  functions  can  modify  the  contents  of  a  directory  entry.  Function  17H 
(Rename  File)  can  be  used  to  change  the  name  field  in  any  directory  entry,  including  hid¬ 
den  or  system  files,  subdirectories,  and  the  volume  label.  Related  Function  56H  (Rename 
File)  also  changes  the  name  field  of  a  filename  but  cannot  rename  a  volume  label  or  a  hid¬ 
den  or  system  file.  However,  it  can  be  used  to  move  a  directory  entry  from  one  directory  to 
another.  (This  capability  is  restricted  to  filenames  only;  subdirectory  entries  cannot  be 
moved  with  Function  56H.) 

Functions  43H  (Get/Set  File  Attributes)  and  57H  (Get/Set  Date/Time  of  File)  can  be  used 
to  modify  specific  fields  in  a  directory  entry.  Function  43H  can  mark  a  directory  entry  as  a 
hidden  or  system  file,  although  it  cannot  modify  the  volume  label  or  subdirectory  bits. 
Function  57H,  as  noted  above,  can  be  used  only  with  a  previously  opened  file;  it  provides 
a  way  to  read  or  update  a  file’s  time  and  date  stamps  without  writing  to  the  file  itself. 

Creating  and  deleting  directories 

Function  39H  (Create  Directory)  exists  only  to  create  directories — that  is,  directory 
entries  with  the  subdirectory  bit  set  to  1.  (Interrupt  21H  functions  that  create  files,  such  as 
Function  3CH,  cannot  assign  the  subdirectory  attribute  to  a  directory  entry.)  The  converse 
function,  3AH  (Remove  Directory),  deletes  a  subdirectory  entry  from  a  directory.  (The 
subdirectory  must  be  completely  empty.)  Again,  Interrupt  21H  functions  that  delete  files 
from  directories,  such  as  Function  4lH,  cannot  be  used  to  delete  subdirectories. 
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Specifying  the  current  directory 

A  call  to  Interrupt  21H  Function  47H  (Get  Current  Directory)  returns  the  pathname  of  the 
current  directory  in  use  by  MS-DOS  to  a  user-supplied  buffer.  The  converse  operation,  in 
which  a  new  current  directory  can  be  specified  to  MS-DOS,  is  performed  by  Function  3BH 
(Change  Current  Directory). 

Programming  examples:  Searching  for  files 

The  subroutines  in  Figure  8-6  below  illustrate  Functions  4EH  and  4FH,  which  use  path 
specifications  passed  as  ASCIIZ  strings  to  search  for  files.  Figure  8-7  applies  these  assem¬ 
bly-language  subroutines  in  a  simple  C  program  that  lists  the  attributes  associated  with 
each  entry  in  the  current  directory.  Note  how  the  directory  search  is  performed  in  the 
WHILE  loop  in  Figure  8-7  by  using  a  global  wildcard  file  specification  (♦.*)  and  by  repeat¬ 
edly  executing  FindNextFileQ  until  no  further  matching  filenames  are  found.  iSee  Pro¬ 
gramming  Example:  Updating  a  Volume  Label  for  examples  of  the  FCB-related  search 
functions,  IIH  and  21H.) 

TITLE  'DIRS. ASM* 


Subroutines  for  DIRDUMP.C 


ARG1  EQU  [bp  +4]  ;  stack  frame  addressing  for  C  arguments 

ARG2  EQU  [bp  +  6] 


-TEXT  SEGMENT  byte  public  'CODE* 

ASSUME  cs:_TEXT 


void  SetDTA (  DTA  ) ; 

char  ♦DTA; 


PUBLIC 

-SetDTA 

PROC 

near 

push 

bp 

mov 

bp,  sp 

mov 

dx,ARG1 

;  DS:DX  -> 

DTA 

mov 

ah, 1 Ah 

;  AH  =  INT 

21 H  function  number 

int 

21h 

;  pass  DTA 

to  MS-DOS 

Figure  8-6.  Subroutines  illustrating  Interrupt  21H Functions  4EH  and  4FH.  ( more) 
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pop  bp 
ret 

_SetDTA  ENDP 


;  int  GetCurrentDir  ( 

♦path  ) ; 

/♦  returns  error  code  ♦/ 

;  char 

♦path; 

/♦  pointer  to  buffer  to  contain  path  ♦/ 

PUBLIC  -GetCurrentDir 

—GetCurrentDir 

PROC 

near 

push 

bp 

mov 

bp  /  sp 

push 

si 

mov 

si/ARG1 

;  DS:SI  ->  buffer 

xor 

dl,dl 

;  DL  =  0  (default  drive  number) 

mov 

ah,47h 

;  AH  =  INT  21 H  function  number 

int 

21h 

;  call  MS-DOS;  AX  =  error  code 

jc 

L01 

;  jump  if  error 

xor 

ax,  ax 

;  no  error,  return  AX  =  0 

L01  : 

pop 

si 

pop 

bp 

ret 

—GetCurrentDir 

ENDP 

;  int  FindFirstFile ( 

path,  attribute  ) ; 

/♦  returns  error  code  ♦/ 

;  char 

♦path, 

;  int 

attribute; 

PUBLIC  -FindFirstFile 

—FindFirstFile 

PROC 

near 

push 

bp 

mov 

bp,sp 

mov 

dx,ARG1 

;  DS:DX  ->  path 

mov 

cx, ARG2 

;  CX  =  attribute 

mov 

ah, 4Eh 

;  AH  =  INT  21 H  function  number 

int 

21h 

;  call  MS-DOS;  AX  =  error  code 

jc 

L02 

;  jump  if  error 

Figure  8-6.  Continued.  (more) 
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xor 

ax,  ax 

;  no  error,  return  AX  = 

0 

L02: 

pop 

bp 

ret 

—FindFirstFile 

ENDP 

;  int  FindNextFile 0 ; 

/*  returns  error  code  */ 

PUBLIC 

—FindNextFile 

—FindNextFile 

PROC 

near 

push 

bp 

mov 

bp,sp 

mov 

ah, 4Fh 

;  AH  =  INT  21 H  function 

number 

int 

21h 

;  call  MS-DOS;  AX  =  error  code 

jc 

LOS 

;  jump  if  error 

xor 

ax,  ax 

;  if  no  error,  set  AX  = 

0 

LOS: 

pop 

bp 

ret 

—FindNextFile 

ENDP 

-TEXT 

ENDS 

-DATA 

SEGMENT 

word  public  * 

DATA* 

CurrentDir 

DB 

64  dup{?) 

DTA 

DB 

64  dup(?) 

-DATA  ENDS 

END 

Figure  8-6.  Continued. 
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/*  DIRDUMP.C  */ 

#define  AllAttributes  0x3F  /*  bits  set  for  all  attributes  */ 

main ( ) 

{ 

static 
int 
int 


struct 

i 

char 

reserved [21 ] ; 

char 

attrib; 

int 

time; 

int 

date; 

long 

size; 

char 

name [13]; 

} 

DTA; 

/*  display  current  directory  name  */ 

ErrorCode  =  GetCurrentDir (  CurrentDir  ); 
if (  ErrorCode  ) 

{ 

printf(  "\nError  %d:  GetCurrentDir”,  ErrorCode  ); 
exit (  1  ) ; 

} 


char  CurrentDir [ 64 1  ; 
ErrorCode; 

FileCount  =0; 


printf(  ”\nCurrent  directory  is  \\%s”,  CurrentDir  ); 


/*  display  files  and  attributes  */ 

SetDTA(  &DTA  );  /*  pass  DTA  to  MS-DOS  ♦/ 

ErrorCode  =  FindFirstFile (  AllAttributes  ); 

while  (  ! ErrorCode  ) 

{ 

printf(  "\n%12s  —  ”,  DTA. name  ); 

ShowAttributes (  DTA.attrib  ); 

++FileCount ; 

ErrorCode  =  FindNextFile  (  ); 

} 

/*  display  file  count  and  exit  */ 

printf(  ”\nCurrent  directory  contains  %d  filesXn”,  FileCount  ); 
return (  0  ) ; 

} 

Figure  8-7.  The  complete  DIRDUMP.C  program. 


(more) 
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ShowAttributes (  a  ) 
int  a; 

{ 

int  i; 

int  mask  =  1 ; 

static  char  *AttribName [ ]  = 

{ 

"read-only  ", 

"hidden  ", 

"system  ", 

"volume  ", 

"subdirectory  ", 

"archive  " 

}; 


f or (  i=0;  i<6;  i++  )  /*  test  each  attribute  bit  */ 

{ 

if (  a  &  mask  ) 

printf  (  AttribName [i]  ) ;  /*  display  a  message  if  bit  is  set  */ 

mask  =  mask  «  1 ; 

} 


Figures-?.  Continued. 

Programming  example:  Updating  a  volume  label 

To  create,  modify,  or  delete  a  volume-label  directory  entry,  the  Interrupt  21H  functions 
that  work  with  FCBs  should  be  used.  Figure  8-8  contains  four  subroutines  that  show  how  to 
search  for,  rename,  create,  or  delete  a  volume  label  in  MS-DOS  versions  2.0  and  later. 

TITLE  ’VOLS.ASM' 


;  C-callable  routines  for  manipulating  MS-DOS  volume  labels. 
;  Note:  These  routines  modify  the  current  DTA  address. 


ARG1 

EQU 

[bp  +  4] 

;  stack  frame  addressing 

DGROUP 

GROUP 

-DATA 

-TEXT 

SEGMENT  byte  public 

' CODE ' 

ASSUME 

cs:-TEXT,ds: 

:  DGROUP 

Figure  8-8.  Subroutines  for  manipulating  volume  labels.  (more) 
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char  *GetVolLabel 0 ; 


/*  returns  pointer  to  volume  label  name  */ 


PUBLIC 

—GetVolLabel 

—GetVolLabel 

PROC 

near 

push 

bp 

mov 

bp,  sp 

push 

si 

push 

di 

call 

SetDTA 

;  pass  DTA  address  to  MS-DOS 

mov 

dx, offset 

DGROUP : ExtendedFCB 

mov 

ah, 1 1h 

;  AH  =  INT  21 H  function  number 

int 

21h 

;  Search  for  First  Entry 

test 

al,  al 

jnz 

L01 

;  label  found  so  make  a  copy 

mov 

si, offset 

DGROUP: DTA  +  8 

mov 

di, of f set 

DGROUP iVolLabel 

call 

CopyName 

mov 

ax, offset 

DGROUP :VolLabel  ;  return  the  copy's  address 

jmp 

short  L02 

L01  : 

xor 

ax,  ax 

;  no  label,  return  0  (null  pointer) 

L02: 

pop 

di 

pop 

si 

pop 

bp 

ret 

-GetVolLabel 

ENDP 

;  int  RenameVolLabel ( 

label  ) ; 

/*  returns  error  code  */ 

;  char 

♦label; 

/*  pointer  to  new  volume  label  name  */ 

PUBLIC 

—RenameVolLabel 

—RenameVolLabel 

PROC 

near 

push 

bp 

mov 

bp,sp 

push 

si 

push 

di 

Figure  8-8.  Continued. 


(more) 
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mov 

mov 

call 

mov 

mov 

call 

mov 

mov 

int 

xor 

pop 

pop 

pop 

ret 

—RenameVolLabel  ENDP 


si, offset  DGROUP : VolLabel  ;  DS:SI  ->  old  volume  name 

di, offset  DGROUP: Name 1 

CopyName  ;  copy  old  name  to  FCB 

si, ARG1 

di, offset  DGROUP :Name2 

CopyName  ;  copy  new  name  into  FCB 


dx, offset 

DGROUP : ExtendedFCB 

;  DS:DX 

ah, 17h 

;  AH  =  INT 

21H 

function 

21h 

;  rename 

ah,  ah 

;  AX  =  OOH 

(success)  or 

->  FCB 
number 

OFFH  (failure) 


di  ;  restore  registers  and  return 

si 

bp 


int  NewVolLabel (  label  ) ; 


/*  returns  error  code  */ 


‘label; 

/*  pointer  to  new  volume 

PUBLIC 

-NewVolLabel 

PROC 

near 

push 

bp 

mov 

bp,  sp 

push 

si 

push 

di 

mov 

si, ARG 1 

mov 

di, of fset 

DGROUP: Name 1 

call 

CopyName 

;  copy  new  name  to  FCB 

mov 

dx, offset 

DGROUP : ExtendedFCB 

mov 

ah,16h 

;  AH  =  INT  21 H  function  ] 

int 

21h 

;  create  directory  entry 

xor 

ah,  ah 

;  AX  =  OOH  (success)  or  1 

pop 

di 

;  restore  registers  and  : 

pop 

si 

pop 

bp 

ret 

ENDP 

-NewVolLabel 


-NewVolLabel 


Figure  8-8.  Continued. 


(more) 
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int  DeleteVolLabel ()  ; 


/*  returns  error  code  */ 


PUBLIC  -DeleteVolLabel 
—DeleteVolLabel  PROC  near 


push 

bp 

mov 

bp,sp 

push 

si 

push 

di 

mov 

si, of fset 

DGROUP:VolLabel 

mov 

di, of fset 

DGROUPiNamel 

call 

CopyName 

;  copy  current  volume  name  to  FCB 

mov 

dx, offset 

DGROUP : ExtendedFCB 

mov 

ah,13h 

;  AH  =  INT  21 H  function  number 

int 

21h 

;  delete  directory  entry 

xor 

ah,  ah 

;  AX  =  OOH  (success)  or  OFFH  (failure) 

pop 

di 

;  restore  registers  and  return 

pop 

si 

pop 

bp 

ret 

—DeleteVolLabel  ENDP 


miscellaneous  subroutines 


SetDTA 


SetDTA 


PROC  near 


push  ax  ;  preserve  registers  used 

push  dx 


mov 

dx, offset 

DGROUP : DTA 

DS:DX  ->  DTA 

mov 

ah, 1 Ah 

;  AH  =  INT  21 H  function 

number 

int 

21h 

;  set  DTA 

pop 

dx 

;  restore 

registers  and 

return 

pop 

ax 

ret 

ENDP 


Figure  8-8.  Continued. 


(more) 
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CopyName 

PROC 

near 

push 

ds 

pop 

es 

mov 

cx,  1 1 

L1 1  : 

lodsb 

test 

al,  al 

jz 

stosb 

L12 

loop 

L1 1 

L12: 

mov 

al,  • 

rep 

ret 

stosb 

CopyName 

ENDP 

-TEXT 

ENDS 

-DATA 

SEGMENT 

word  public 

VolLabel 

DB 

11  dup(0),0 

ExtendedFCB 

DB 

OFFh 

DB 

5  dup(O) 

DB 

1000b 

DB 

0 

Namel 

DB 

11  dup(’?’) 

DB 

5  dup ( 0 ) 

Name  2 

DB 

11  dup(O) 

DB 

9  dup(O) 

DTA 

DB 

64  dup(O) 

;  Caller:  SI  ->  ASCIIZ  source 
;  DI  ->  destination 

;  ES  =  DGROUP 
;  length  of  name  field 

;  copy  new  name  into  FCB  . . 

;  . .  until  null  character  is  reached 

;  pad  new  name  with  blanks 


' DATA ’ 


;  must  be  OFFH  for  extended  FCB 
;  (reserved) 

;  attribute  byte  (bit  3=1) 

;  default  drive  ID 
;  global  wildcard  name 
;  (unused) 

;  second  name  (for  renaming  entry) 
;  (unused) 


-DATA  ENDS 


END 


Figure  8-8.  Continued. 


Richard  Wilton 
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Article  9 

Memory  Management 


Personal  computers  that  are  MS-DOS  compatible  can  be  outfitted  with  as  many  as  three 
kinds  of  random-access  memory  (RAM):  conventional  memory,  expanded  memory,  and 
extended  memory. 

All  MS-DOS  machines  have  at  least  some  conventional  memory,  but  the  presence  of  ex¬ 
panded  or  extended  memory  depends  on  the  installed  hardware  options  and  the  model  of 
microprocessor  on  which  the  computer  is  based.  Each  storage  class  has  its  own  capabil¬ 
ities,  characteristics,  and  limitations.  Each  also  has  its  own  management  techniques,  which 
are  the  subject  of  this  chapter. 


Conventional  Memory 

Conventional  memory  is  the  term  for  the  up  to  1  MB  of  memory  that  is  directly  addressable 
by  an  Intel  8086/8088  microprocessor  or  by  an  80286  or  80386  microprocessor  running  in 
real  mode  (8086-emulation  mode).  Physical  addresses  for  references  to  conventional 
memory  are  generated  by  a  l6-bit  segment  register,  which  acts  as  a  base  register  and  holds 
a  paragraph  address,  combined  with  a  l6-bit  offset  contained  in  an  index  register  or  in  the 
instruction  being  executed. 

On  IBM  PCs  and  compatibles,  MS-DOS  and  the  programs  that  run  under  its  control  occupy 
the  bottom  640  KB  or  less  of  the  conventional  memory  space.  The  memory  space  above 
the  640  KB  mark  is  partitioned  among  ROM  (read-only  memory)  chips  on  the  system 
board  that  contain  various  primitive  device  handlers  and  test  programs  and  among  RAM 
and  ROM  chips  on  expansion  boards  that  are  used  for  input  and  output  buffers  and  for  ad¬ 
ditional  device-dependent  routines. 

The  bottom  640  KB  of  memory  administered  by  MS-DOS  is  divided  into  three  zones 
(Figure  9-1): 

•  The  interrupt  vector  table 

•  The  operating  system  area 

•  The  transient  program  area 

The  interrupt  vector  table  occupies  the  lowest  1024  bytes  of  memory  (locations  00000- 
003FFH);  its  address  and  length  are  hard-wired  into  the  processor  and  cannot  be  changed. 
Each  doubleword  position  in  the  table  is  called  an  interrupt  vector  and  contains  the  seg¬ 
ment  and  offset  of  an  interrupt  handler  routine  for  the  associated  hardware  or  software  in¬ 
terrupt  number.  Interrupt  handler  routines  are  usually  built  into  the  operating  system. 
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100000H(1  MB) 


A0000H(640KB) 


Boundary  varies 


00400H(1KB) 

OOOOOH 

Figure  9-1.  A  diagram  showing  conventional  memory  in  an  IBM  PC-compatible  MS-DOS  system.  The  bottom 
1024  bytes  of  memory  are  used for  the  interrupt  vector  table.  The  memory  above  the  vector  table,  up  to  the  640 
KB  boundary,  is  available for  use  by  MS-DOS  and  the  programs  that  run  under  its  control.  The  top  384  KB  are 
used  for  the  ROM  BIOS,  other  device-control  and  diagnostic  routines,  and  memory-mapped  input  and  output. 

but  in  Special  cases  application  programs  can  contain  handler  routines  of  their  own. 
Vectors  for  interrupt  numbers  that  are  not  used  for  software  linkages  or  by  some  hardware 
device  are  usually  initialized  by  the  operating  system  to  point  to  a  simple  interrupt  return 
(IRET)  instruction  or  to  a  routine  that  displays  an  error  message. 

The  operating-system  area  begins  immediately  above  the  interrupt  vector  table  and 
holds  the  operating  system  proper,  its  tables  and  buffers,  any  additional  installable  device 
drivers  specified  in  the  CONFIG.SYS  file,  and  the  resident  portion  of  the  COMMAND.COM 
command  interpreter.  The  amount  of  memory  occupied  by  the  operating-system  area 
varies  with  the  version  of  MS-DOS  being  used,  the  number  of  disk  buffers,  and  the  number 
and  size  of  installed  device  drivers. 

The  transient  program  area  (TPA)  is  the  remainder  of  RAM  above  the  operating-system 
area,  extending  to  the  640  KB  limit  or  to  the  end  of  installed  RAM  (whichever  is  smaller). 
External  MS-DOS  commands  (such  as  CHKDSK)  and  other  programs  are  loaded  into  the 
TPA  for  execution.  The  transient  portion  of  COMMAND.COM  also  runs  in  this  area. 

The  TPA  is  organized  into  a  structure  called  the  memory  arena,  which  is  divided  into  por¬ 
tions  called  arena  entries  (or  memory  blocks).  These  entries  are  allocated  in  paragraph 
(l6-byte)  multiples  and  can  be  as  small  as  one  paragraph  or  as  large  as  the  entire  TPA. 

Each  arena  entry  is  preceded  by  a  control  structure  called  an  arena  entry  header,  which 
contains  information  indicating  the  size  and  status  of  the  arena  entry. 


ROM  Bios 
additional  ROM  code 
on  expansion  boards, 
memory-mapped  I/O 
buffers 


Transient 
program  area 


MS-DOS  and 
its  buffers,  tables, 
and  device  drivers 


Interrupt  vector  table 
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MS-DOS  inspects  the  arena  entry  headers  whenever  a  function  requesting  a  memory- 
block  allocation,  modification,  or  release  is  issued;  when  a  program  is  loaded  and  exe¬ 
cuted  with  the  EXEC  function  (Interrupt  21H  Function  4BH);  or  when  a  program  is  termi¬ 
nated.  If  any  of  the  arena  entry  headers  appear  to  be  damaged,  MS-DOS  returns  an  error  to 
the  calling  process.  If  that  process  is  COMMAND.COM,  COMMAND.COM  then  displays 
the  message  Memory  allocation  error  and  halts  the  system. 

MS-DOS  support  for  conventional  memory  management 

The  MS-DOS  kernel  supports  three  memory-management  functions,  invoked  with  Inter- 
rupt  21H,  that  operate  on  the  TPA: 

•  Function  48H  (Allocate  Memory  Block) 

•  Function  49H  (Free  Memory  Block) 

•  Function  4AH  (Resize  Memory  Block) 

These  three  functions  (Table  9-1)  can  be  called  by  application  programs,  by  the  command 
processor,  and  by  MS-DOS  itself  to  dynamically  allocate,  resize,  and  release  arena  entries 
as  they  are  needed.  See  SYSTEM  CALLS:  Interrupt  21h:  Functions  48H;  49H;  4AH. 


Table  9-1.  MS-DOS  Memory-Management  Functions. 


Function  Name 

Calimth 

Returns 

Allocate  Memory  Block 

AH  =  48H 

BX  =  paragraphs  needed 

AX  =  segment  of  allocated 
block 

If  failed: 

BX  =  size  of  largest  available 
block  in  paragraphs 

Free  Memory  Block 

AH  =  49H 

ES  =  segment  of  block  to 
release 

nothing 

Resize  (Allocated) 

AH  =  4AH 

If  failed: 

Memory  Block 

BX  =  new  size  of  block  in 
paragraphs 

ES  =  segment  of  block  to 
resize 

BX  =  maximum  size 

for  block  in  paragraphs 

Get/Set  Allocation 

AH  =  58H 

If  getting: 

Strategy* 

AL  =  OOH  (get  strategy) 

OlH  (set  strategy) 

If  setting: 

BX  =  strategy: 

OOH  =  first  fit 

OlH  =  best  fit 

02H  =  last  fit 

AX  =  strategy  code 

•  MS-DOS  versions  3.x  only. 
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When  the  MS-DOS  kernel  receives  a  memory-allocation  request,  it  inspects  the  chain  of 
arena  entry  headers  to  find  a  free  arena  entry  that  can  satisfy  the  request.  The  memory 
manager  can  use  any  of  three  allocation  strategies: 

•  First  fit-the  arena  entry  at  the  lowest  address  that  is  large  enough  to  satisfy  the 
request 

•  Best  fit-the  smallest  available  arena  entry  that  satisfies  the  request,  regardless  of  its 
position 

•  Last  fit-the  arena  entry  at  the  highest  address  that  is  large  enough  to  satisfy  the 
request 

If  the  arena  entry  selected  is  larger  than  the  size  needed  to  fulfill  the  request,  the  arena 
entry  is  divided  and  the  program  is  given  an  arena  entry  exactly  the  size  it  requires.  A  new 
arena  entry  header  is  then  created  for  the  remaining  portion  of  the  original  arena  entry;  it 
is  marked  “unowned”  and  can  be  used  to  satisfy  subsequent  allocation  calls. 

Research  on  allocation  strategies  has  demonstrated  that  the  first-fit  approach  is  most 
efficient,  and  this  is  the  default  strategy  used  by  MS-DOS.  However,  in  MS-DOS  versions 
3.0  and  later,  an  application  program  can  select  a  different  strategy  for  the  memory  man¬ 
ager  with  Interrupt  21H  Function  58H  (Get/Set  Allocation  Strategy).  See  SYSTEM  CALLS: 
Interrupt  21h:  Function  58H. 

Using  the  memory-management  functions 

When  a  program  begins  executing,  it  already  owns  two  arena  entries  allocated  on  its 
behalf  by  the  MS-DOS  EXEC  function  (Interrupt  21H  Function  4BH).  The  first  entry  holds 
the  program’s  environment  and  is  just  large  enough  to  contain  this  information;  the  second 
entry  (called  the  program  block  in  this  article)  contains  the  program’s  PSP,  code,  data,  and 
stack. 

The  amount  of  memory  MS-DOS  allocates  to  the  program  block  for  a  newly  loaded  tran¬ 
sient  program  depends  on  its  type  (.COM  or  .EXE).  Under  typical  conditions,  a  .COM  pro¬ 
gram  is  allocated  all  of  the  first  arena  entry  that  is  large  enough  to  hold  the  contents  of  its 
file,  plus  256  bytes  for  the  PSP  and  at  least  2  bytes  for  the  stack.  Because  the  TP  A  is  seldom 
fragmented  into  more  than  one  arena  entry  before  a  program  is  loaded,  a  .COM  program 
usually  ends  up  owning  all  the  memory  in  the  system  that  does  not  belong  to  the  operat¬ 
ing  system  itself — memory  divided  between  a  relatively  small  environment  and  a  com¬ 
paratively  immense  program  block. 

The  amount  of  memory  allocated  to  a  .EXE  program,  on  the  other  hand,  is  controlled 
by  two  fields  called  MINALLOC  and  MAXALLOC  in  the  .EXE  program  file  header.  The 
MINALLOC  field  tells  the  MS-DOS  loader  how  many  paragraphs  of  memory,  in  addition  to 
the  memory  required  to  hold  the  initialized  code  and  the  data  present  in  the  file,  must  be 
available  for  the  program  to  execute  at  all.  The  MAXALLOC  field  contains  the  maximum 
number  of  excess  paragraphs,  if  available,  to  allocate  to  the  program. 
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The  default  value  placed  in  MAXALLOC  by  the  Microsoft  Object  Linker  is  FFFFH  para¬ 
graphs,  corresponding  to  1  MB.  Consequently,  a  .EXE  program  is  typically  allocated  all  of 
available  memory  when  it  is  loaded,  as  is  a  .COM  file.  Although  it  is  possible  to  set  the 
MAXALLOC  field  to  other,  smaller  values  with  the  linker’s  /CPARMAXALLOC  switch  or 
with  the  EXEMOD  utility  supplied  with  Microsoft  language  compilers,  few  programmers 
bother  to  do  so. 

In  short,  when  a  program  begins  executing,  it  usually  owns  all  of  available  memory — 
frequently  much  more  memory  than  it  needs.  If  the  program  wants  to  be  well  behaved  in 
its  use  of  memory  and,  possibly,  load  child  programs  as  well,  it  should  immediately  release 
any  extra  memory.  In  assembly-language  programs,  the  extra  memory  is  released  by  call¬ 
ing  Interrupt  21H  Function  4AH  (Resize  Memory  Block)  with  the  segment  of  the  program’s 
PSP  in  the  ES  register  and  the  number  of  paragraphs  of  memory  to  retain  for  the  program’s 
use  in  the  BX  register.  iSee  Figures  9-2  and  9-3.)  In  most  high-level  languages,  such  as 
Microsoft  C,  excess  memory  is  released  by  the  rim-time  library’s  startup  module. 


—TEXT  segment  para  public  ’CODE' 


org  lOOh 

assume  cs TEXT, ds :_TEXT, es :_TEXT, ss TEXT 


mam  proc  near 


mov  sp, offset  stk 


mov 

bx, offset  stk 

mov 

cl, 4 

shr 

bx,  cl 

inc 

bx 

mov 

ah, 4ah 

int 

21h 

jc 

error 

main  endp 


;  entry  point  from  MS-DOS 
;  CS  =  DS  =  ES  =  SS  =  PSP 

;  first  move  our  stack 
;  to  a  safe  place... 

;  now  release  extra  memory. . . 

;  calculate  paragraphs  to  keep 
;  (divide  offset  of  end  of 
;  program  by  16  and  round  up) 

;  Fxn  4AH  =  resize  mem  block 
;  transfer  to  MS-DOS 
;  jump  if  resize  failed 

;  otherwise  go  on  with  work. . . 


(more) 

Figure  9-2.  An  example  of  a  .COM  program  releasing  excess  memory  after  it  receives  control  from  MS-DOS. 
Interrupt  21H  Function  4AH  is  called  with  the  segment  address  of  the  program ’s  PSP  in  register  ES  and  the 
number  of  paragraphs  of  memory  to  retain  in  register  BX. 
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dw 

64  dup  (?) 

stk 

equ 

$ 

;  base  of  new  stack  area 

-TEXT 

ends 

end 

main 

;  defines  program  entry  point 

Figure  9-2.  Continued. 


_TEXT  segment  word  public  'CODE'  ;  executable  code  segment 

assume  cs  :_TEXT,  ds  :__DATA,  ss :  STACK 

main  proc  far  ;  entry  point  from  MS-DOS 

;  CS  =  —TEXT  segment, 

;  DS  =  ES  =  PSP 


mov 

mov 


ax,— DATA 
ds,  ax 


;  set  DS  =  our  data  segment 


mov 

mov 

sub 

add 

inc 

mov 

int 

jc 


ax,  es 
bx,  ss 
bx,ax 

bx, stksize/l 6 
bx 

ah, 4ah 

21h 

error 


give  back  extra  memory... 
let  AX  =  segment  of  PSP  base 
and  BX  =  segment  of  stack  base 
reserve  seg  stack  -  seg  psp 
plus  paragraphs  of  stack 
round  up 

Fxn  4AH  =  resize  memory  block 
transfer  to  MS-DOS 
jump  if  resize  failed 


main  endp 
-TEXT  ends 

—DATA  segment  word  public  'DATA'  ;  static  &  variable  data 


—DATA  ends 


(more) 

Figure  9-3.  An  example  of  a  .EXE  program  releasing  excess  memory  after  it  receives  control  from  MS-DOS. 
This  particular  code  sequence  depends  on  the  segment  order  shown.  When  a  .EXE  program  is  linked  from 
many  different  object  modules,  other  techniques  may  be  needed  to  determine  the  amount  of  memory  occupied 
by  the  program  at  run  time. 
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STACK  segment  para  stack  'STACK* 
db  stksize  dup  (?) 

STACK  ends 

end  main  ;  defines  program  entry  point 

Figure  9-3-  Continued. 

Later,  if  the  transient  program  needs  additional  memory  for  a  buffer,  table,  or  other  work 
area,  it  can  call  Interrupt  21H  Function  48H  (Allocate  Memory  Block)  with  the  desired 
number  of  paragraphs.  If  a  sufficiently  large  block  of  memory  is  available,  MS-DOS  creates 
a  new  arena  entry  of  the  requested  size  and  returns  a  pointer  to  its  base  in  the  form  of  a 
segment  address  in  the  AX  register.  If  an  arena  entry  of  the  requested  size  cannot  be  cre¬ 
ated,  MS-DOS  returns  an  error  code  in  the  AX  register  and  the  size  in  paragraphs  of  the 
largest  available  block  of  memory  in  the  BX  register.  The  application  program  can  inspect 
this  value  to  determine  whether  it  can  continue  in  a  degraded  fashion  with  a  smaller 
amount  of  memory. 

When  a  program  finishes  using  an  allocated  arena  entry,  it  should  promptly  call  Interrupt 
21H  Function  49H  to  release  it.  This  allows  MS-DOS  to  collect  small  blocks  of  freed  mem¬ 
ory  into  contiguous  arena  entries  and  reduces  the  chance  that  future  allocation  requests  by 
the  same  program  will  fail  because  of  memory  fragmentation.  In  any  case,  all  arena  entries 
owned  by  a  program  are  released  when  the  program  terminates  with  Interrupt  20H  or 
with  Interrupt  21H  Function  OOH  or  4CH. 

A  program  skeleton  demonstrating  the  use  of  dynamic  memory  allocation  services  is 
shown  in  Figure  9-4. 


mov 

bx,800h 

;  800H  paragraphs  =  32  KB 

mov 

ah,48h 

;  Fxn  48H  =  allocate  block 

int 

21h 

;  transfer  to  MS-DOS 

jc 

error 

;  jump  if  allocation  failed 

mov 

bufseg, ax 

;  save  segment  of  block 

;  open  working  file... 

mov 

dx, offset  filel 

;  DS:DX  =  filename  address 

mov 

ax, 3d00h 

;  Fxn  3DH  =  open,  read  only 

int 

21h 

;  transfer  to  MS-DOS 

jc 

error 

;  jump  if  open  failed 

mov 

handlel ,  ax 

;  save  handle  for  work  file 

(more) 

Figure  9-4.  A  skeleton  example  of  dynamic  memory  allocation.  The  program  requests  a  32  KB  memory  block, 
uses  it  to  copy  its  working  file  to  a  backup  file,  and  then  releases  the  memory  block.  Note  the  use  of  ASSUME 
directives  to  force  the  assembler  to  generate  proper  segment  overrides  on  references  to  variables  containing  file 
handles. 
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; 

create  backup  file... 

mov 

dx, offset  file2  ; 

DS:DX  =  filename  address 

mov 

cx,  0 

CX  =  attribute  (normal) 

mov 

ah, 3ch 

/ 

Fxn  3CH  =  create  file 

int 

21h 

9 

transfer  to  MS-DOS 

jc 

error 

f 

jump  if  create  failed 

mov 

handle2, ax 

save  handle  for  backup  file 

push 

ds 

; 

set  ES  =  our  data  segment 

pop 

es 

mov 

ds,bufseg 

; 

set  DS:DX  =  allocated  block 

xor 

dx,dx 

assume 

dsrNOTHING, 

es:_DATA  ;  tell  assembler 

read  working  file... 

mov 

bx,handle1 

handle  for  work  file 

mov 

cx, 8000h 

/ 

try  to  read  32  KB 

mov 

ah,3fh 

/ 

Fxn  3FH  =  read 

int 

21h 

/ 

transfer  to  MS-DOS 

jc 

error 

/ 

jump  if  read  failed 

or 

ax,  ax 

was  end  of  file  reached? 

jz 

done 

9 

yes,  exit  this  loop 

9 

now  write  backup  file... 

mov 

cx,  ax 

9 

set  write  length  =  read  length 

mov 

bx,handle2 

9 

handle  for  backup  file 

mov 

ah,40h 

9 

Fxn  40H  =  write 

int 

21h 

9 

transfer  to  MS-DOS 

jc 

error 

9 

jump  if  write  failed 

cmp 

ax,  cx 

9 

was  write  complete? 

jne 

error 

9 

no,  disk  must  be  full 

jmp 

next 

9 

transfer  another  record 

push 

es 

; 

restore  DS  =  data  segment 

pop 

ds 

assume 

ds  :_DATA,  es 

: NOTHING  ;  tell  assembler 

release  allocated  block... 

mov 

es,buf seg 

segment  base  of  block 

mov 

ah,49h 

Fxn  49H  =  release  block 

int 

21h 

transfer  to  MS-DOS 

jc 

error 

(should  never  fail) 

now  close  backup  file... 

mov 

bx, handle2 

handle  for  backup  file 

mov 

ah, 3eh 

Fxn  3EH  =  close 

int 

21h 

transfer  to  MS-DOS 

jc 

error 

jump  if  close  failed 

Figure  9-4.  Continued. 


(more) 
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filel  db 
file2  db 


'MYFILE.DAT* , 0  ;  name  of  working  file 

'MYFILE.BAK',0  ;  name  of  backup  file 


handlel  dw  ? 
handle2  dw  ? 
bufseg  dw  ? 


;  handle  for  working  file 
;  handle  for  backup  file 
;  segment  of  allocated  block 


Figure  9-4.  Continued. 


Expanded  Memory 

The  original  Expanded  Memory  Specification  (EMS)  version  3.0  was  developed  as  a  joint 
effort  of  Lotus  Development  Corporation  and  Intel  Corporation  and  was  announced  at  the 
Spring  COMDEX  in  1985.  The  EMS  was  designed  to  provide  a  uniform  means  for  applica¬ 
tions  running  on  8086/8088-based  personal  computers,  or  on  80286/80386-based  com¬ 
puters  in  real  mode,  to  circumvent  the  1  MB  limit  on  conventional  memory,  thus  providing 
such  programs  with  much  larger  amounts  of  fast  random-access  storage.  The  EMS  version 
3.2,  modified  from  3.0  to  add  support  for  multitasking  operating  systems,  was  released 
shortly  afterward  as  a  joint  effort  of  Lotus,  Intel,  and  Microsoft. 

The  EMS  is  a  functional  definition  of  a  bank-switched  memory  subsystem;  it  consists  of 
user-installable  boards  that  plug  into  the  IBM  PC’s  expansion  bus  and  a  resident  driver  pro¬ 
gram  called  the  Expanded  Memory  Manager  (EMM)  that  is  provided  by  the  board  manu¬ 
facturer.  As  much  as  8  MB  of  expanded  memory  can  be  installed  in  a  single  machine. 
Expanded  memory  is  made  available  to  application  software  in  16  KB  pages,  which  are 
mapped  by  the  EMM  into  a  contiguous  64  KB  area  called  the  page  frame  somewhere 
above  the  conventional  memory  area  used  by  MS-DOS  (0-640  KB).  An  application  pro¬ 
gram  can  thus  access  as  many  as  four  l6  KB  expanded  memory  pages  simultaneously.  The 
location  of  the  page  frame  is  user  configurable  so  that  it  will  not  conflict  with  other  hard¬ 
ware  options  (Figure  9-5). 

The  Expanded  Memory  Manager 

The  Expanded  Memory  Manager  provides  a  hardware-independent  interface  between 
application  programs  and  the  expanded  memory  board(s).  The  EMM  is  supplied  by  the 
board  manufacturer  in  the  form  of  an  installable  character-device  driver  and  is  linked  into 
MS-DOS  by  a  DEVICE  directive  added  to  the  CONFIG.SYS  file  on  the  system  startup  disk. 

Internally,  the  EMM  is  divided  into  two  distinct  components  that  can  be  referred  to  as  the 
driver  and  the  manager.  The  driver  portion  mimics  some  of  the  actions  of  a  genuine  in¬ 
stallable  device  driver,  in  that  it  includes  Initialization  and  Output  Status  subfunctions  and 
a  valid  device  header.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Customiz¬ 
ing  MS-DOS:  Installable  Device  Drivers. 
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Expanded  memory 


Figure  9-5.  A  sketch  of  the  relationship  of  expanded  memory  to  conventional  memory;  16  KB  pages  of 
expanded  memory  are  mapped  into  a  64  KB  area,  called  the  page  frame,  above  the  640 KB  boundary.  The 
location  of  the  page  frame  can  be  configured  by  the  user  to  eliminate  conflicts  with  ROMs  or  I/O  buffers  on 
expansion  boards. 

The  second,  and  major,  element  of  the  EMM  is  the  true  interface  between  application  soft¬ 
ware  and  the  expanded  memory  hardware.  Several  classes  of  services  provide 

•  Status  of  the  expanded  memory  subsystem 

•  Allocation  of  expanded  memory  pages 

•  Mapping  of  logical  pages  into  physical  memory 

•  Deallocation  of  expanded  memory  pages 

•  Support  for  multitasking  operating  systems 

•  Diagnostic  routines 

Application  programs  communicate  with  the  EMM  directly  by  means  of  a  software  inter¬ 
rupt  (Interrupt  67H).  The  MS-DOS  kernel  does  not  take  part  in  expanded  memory 
manipulations  and  does  not  use  expanded  memory  for  its  own  purposes. 
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Checking  for  expanded  memory 

Before  it  attempts  to  use  expanded  memory  for  storage,  an  application  program  must 
establish  that  the  EMM  is  present  and  functional,  and  then  it  must  use  the  manager  portion 
of  the  EMM  to  check  the  status  of  the  memory  boards  themselves.  There  are  two  methods 
a  program  can  use  to  test  for  the  existence  of  the  EMM. 

The  first  method  is  to  issue  an  Open  File  or  Device  request  (Interrupt  21H  Function  3DH) 
using  the  guaranteed  device  name  of  the  EMM  driver:  EMMXXXXO.  If  the  open  operation 
succeeds,  one  of  two  conditions  is  indicated — either  the  driver  is  present  or  a  file  with  the 
same  name  exists  in  the  current  directory  of  the  default  disk  drive.  To  rule  out  the  latter 
possibility,  the  application  can  issue  lOCTL  Get  Device  Information  (Interrupt  21H  Func¬ 
tion  44H  Subfunction  OOH)  and  Check  Output  Status  (Interrupt  21H  Function  44H  Subfunc¬ 
tion  07H)  requests  to  determine  whether  the  handle  returned  by  the  open  operation  is 
associated  with  a  file  or  with  a  device.  In  either  case,  the  handle  that  was  obtained  from 
the  open  function  should  then  be  closed  (Interrupt  21H  Function  3EH)  so  that  it  can  be 
reused  for  another  file  or  device. 

The  second  method  of  testing  for  the  driver  is  to  use  the  address  that  is  found  in  the  vector 
for  Interrupt  67H  to  inspect  the  device  header  of  the  presumed  EMM.  (The  contents  of 
the  vector  can  be  obtained  conveniently  with  Interrupt  21H  Function  35H.)  If  the  EMM  is 
present,  the  name  field  at  offset  OAH  of  the  device  header  contains  the  string  EMMXXXXO. 
This  method  is  nearly  foolproof,  and  it  avoids  the  relatively  high  overhead  of  an  MS-DOS 
open  function.  However,  it  is  somewhat  less  well  behaved  because  it  involves  inspection 
of  memory  that  does  not  belong  to  the  application. 

The  two  methods  of  testing  for  the  existence  of  the  EMM  are  illustrated  in  Figures  9-6  and 
9-7. 


attempt  to  "open”  EMM. . . 


mov 

dx,seg  emm_name  ; 

DS:DX  =  address  of  name 

mov 

ds , dx  ; 

of  EMM 

mov 

dx, offset  emm_name 

mov 

ax,3d00h  ; 

Fxn  3DH,  Mode  =  OOH 

; 

=  open,  read-only 

int 

21  h 

transfer  to  MS-DOS 

jc 

error  ; 

jump  if  open  failed 

;  open  succeeded,  make  sure 
;  it  was  not  a  file... 


(more) 

Figure  9-6.  Testing  for  the  presence  of  the  Expanded  Memory  Manager  with  the  MS-DOS  Open  File  or  Device 
(Interrupt  21H Function  3DH)  and  lOCTL  (Interrupt  21H Function  44H) functions. 


Section  II:  Programming  in  the  MS-DOS  Environment  307 


Part  B:  Programming  for  MS-DOS 


mov 

bx,  ax 

mov 

ax, 4400h 

int 

21h 

jc 

error 

and 

dx, 80h 

jz 

error 

mov 

ax, 4407h 

int 

21h 

jc 

error 

or 

al,  al 

.32 

error 

mov 

ah, 3eh 

int 

21h 

jc 

error 

;  BX  =  handle  from  open 
;  Fxn  44H  Subfxn  OOH 
;  =  lOCTL  Get  Device  Information 
;  transfer  to  MS-DOS 
;  jump  if  lOCTL  call  failed 
;  Bit  7  =  1  if  character  device 
;  jump  if  it  was  a  file 

;  EMM  is  present,  make  sure 
;  it  is  available... 

;  (BX  still  contains  handle) 

;  Fxn  44H  Subfxn  07H 
;  =  lOCTL  Get  Output  Status 
;  transfer  to  MS-DOS 
;  jump  if  lOCTL  call  failed 
;  test  device  status 
;  if  AL  =  0  EMM  is  not  available 

;  now  close  handle  . . . 

;  (BX  still  contains  handle) 

;  Fxn  3EH  =  Close 

;  transfer  to  MS-DOS 
;  jump  if  close  failed 


emm_name  db  'EMMXXXXO',0  ;  guaranteed  device  name  for  EMM 

Figure  9^6.  Continued. 


emm_int  equ  67h 


mov 

al, emm_int 

mov 

ah, 35h 

int 

21h 

;  EMM  software  interrupt 


;  first  fetch  contents  of 
;  EMM  interrupt  vector. . . 

;  AL  =  EMM  int  number 
;  Fxn  35H  =  get  vector 
;  transfer  to  MS-DOS 
;  now  ES:BX  =  handler  address 

;  assume  ESiOOOO  points 
;  to  base  of  the  EMM. . . 


(more) 

Figure  9-  7.  Testing  for  the  presence  of  the  Expanded  Memory  Manager  by  inspecting  the  name field  in  the 
device  driver  header. 
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mov 

di , 1 0  ; 

ES:DI  =  address  of  name 

field  in  device  header 

mov 

si,seg  emm_name  ; 

DS:SI  =  address  of 

mov 

ds,si  ; 

expected  EMM  driver  name 

mov 

si, offset  emm_name 

mov 

cld 

cx,  8  ; 

length  of  name  field 

repz 

cmpsb  ; 

compare  names . . . 

jnz 

error  ; 

jump  if  driver  absent 

emm_name  db  'EMMXXXXO'  ;  guaranteed  device  name  for  EMM 

Figure  9-7.  Continued. 

Using  expanded  memory 

After  establishing  that  the  EMM  is  present,  the  application  program  can  bypass  MS-DOS 
and  communicate  with  the  EMM  directly  by  means  of  software  Interrupt  67H.  The  calling 
sequence  is  as  follows: 

mov  ah, function  ;  AH  selects  EMM  function 

.  ;  Load  other  registers  with 

.  ;  values  specific  to  the 

.  ;  requested  service 

int  67h  ;  Transfer  to  EMM 

In  general,  the  ES:DI  registers  are  used  to  pass  the  address  of  a  buffer  or  an  array,  and  the 
DX  register  is  used  to  hold  an  expanded  memory  “handle.”  Some  EMM  functions  also  use 
other  registers  (chiefly  AL  and  BX)  to  pass  such  information  as  logical  and  physical  page 
numbers.  Table  9-2  summarizes  the  services  available  from  the  EMM. 

Upon  return  from  an  EMM  function  call,  the  AH  register  contains  zero  if  the  function  was 
successful;  otherwise,  AH  contains  an  error  code  with  the  most  significant  bit  set  (Table 
9-3).  Other  values  are  typically  returned  in  the  AL  and  BX  registers  or  in  a  user-specified 
buffer. 
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Function 

Name 

Action 

Call 

Returns 

Comments 

Get  Manager 
Status 

Test  whether  the 
expanded  memory 
software  and  hardware 
are  functional. 

AH  =  40H 

AH  =  status 

This  call  is  used  after  the  program  has  established,  with 
one  of  the  techniques  presented  in  Figures  9-6  and  9-7, 
that  the  EMM  is  present. 

Get  Page 

Frame  Segment 

Obtain  the  segment 
address  of  the  EMM  page 
frame. 

AH  =  41H 

AH  =  status 

BX  =  segment  of  page 
frame,  if  AH  =  OOH 

The  page  frame  is  divided  into  four  l6  KB  pages  that  are 
used  to  map  logical  expanded  memory  pages  into  the 
physical  memory  space  of  the  8086/8088  processor. 

Get  Expanded 
Memory  Pages 

Obtain  the  number 
of  logical  expanded 
memory  pages  present 
in  the  system  and  the 
number  of  pages  that  are 
not  already  allocated. 

AH  =  42H 

AH  =  status 

BX  =  unallocated  EMM 
pages,  if  AH  =  OOH 
DX  =  total  EMM  pages  in 
system 

The  application  need  not  have  already  acquired  an  EMM 
handle  to  use  this  function. 

Allocate 

Expanded 

Memory 

Obtain  an  EMM  handle 
and  allocate  logical 
pages  to  be  controlled  by 
that  handle. 

AH  =  43H 

BX  =  logical  pages 
to  allocate 

AH  =  status 

DX  =  handle,  if  AH  = 

OOH 

This  function  is  equivalent  to  a  file-open  function  for  the 
EMM.  The  handle  returned  is  analogous  to  a  file  handle 
and  owns  a  certain  number  of  EMM  pages.  The  handle 
must  be  used  with  every  subsequent  request  to  map 
memory  and  must  be  released  by  a  close  operation  when 
the  application  is  finished. 

This  function  can  fail  because  either  the  available  EMM 
handles  or  the  EMM  pages  have  been  exhausted. 

Function  42H  can  be  called  by  the  application  to 
determine  the  actual  number  of  pages  available. 

Map  Memory 

Map  one  of  the  logical 
pages  of  expanded 
memory  assigned  to  a 
handle  onto  one  of  the 
four  physical  pages 
within  the  EMM’s  page 
frame. 

AH  =  44H 

AL  =  physical  page 
(0-3) 

BX  =  logical  page 

(0...W-1) 

DX  =  EMM  handle 

AH  =  status 

The  logical  page  number  must  be  in  the  range  0-  w-1, 
where  n  is  the  number  of  logical  pages  previously 
allocated  to  the  EMM  handle  with  Function  43H. 

To  access  the  memory  after  it  has  been  mapped  to  a 
physical  page,  the  application  also  needs  the  segment  of 
the  EMM’s  page  frame,  which  can  be  obtained  with 
Function  4lH. 
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Release  Handle 
and  Memory 

Deallocate  the  logical 
pages  of  expanded 
memory  currently 
assigned  to  a  handle 
and  then  release  the 
handle  itself  for  reuse. 

AH  =  45H 

DX  =  EMM  handle 

AH  =  status 

This  function  is  the  equivalent  of  a  close  operation  on 
a  file.  It  notifies  the  EMM  that  the  application  will  not  be 
making  further  use  of  the  data  it  may  have  stored  within 
expanded  memory  pages. 

Get  EMM 

Version 

Return  the  version 
number  of  the  EMM 
software. 

AH  =  46H 

AH  =  status 

AL  =  EMM  version, 
ifAH  =  00H 

The  returned  value  is  the  version  of  the  EMM  with  which 
the  driver  complies.  The  version  number  is  encoded  as 
BCD,  with  the  integer  part  in  the  upper  4  bits  and  the 
fractional  part  in  the  lower  4  bits. 

Save  Mapping 
(Dontext 

Save  the  contents  of  the 
expanded  memory  page¬ 
mapping  roisters  on 
the  expanded  memory 
boards,  associating  those 
contents  with  a  specific 
EMM  handle. 

AH  =  47H 

DX  =  EMM  handle 

AH  =  status 

This  function  is  designed  for  use  by  interrupt  handlers 
and  resident  drivers  or  utilities  that  must  access  expanded 
memory.  The  handle  supplied  to  the  function  is  the 
handle  that  was  assigned  to  the  interrupt  handler  during 
its  initialization  sequence,  not  to  the  program  that  was 
interrupted. 

Restore 

Mapping 

Context 

Restore  the  contents 
of  all  expanded  memory 
hardware  page-mapping 
roisters  to  the  values 
associated  with  the  given 
handle. 

AH  =  48H 

DX  =  EMM  handle 

AH  =  status 

Use  of  this  function  must  be  balanced  by  a  previous  call 
to  EMM  Function  47H.  It  allows  an  interrupt  handler  or  a 
resident  driver  that  used  expanded  memory  to  restore  the 
mapping  context  to  its  state  at  the  point  of  interruption. 

Get  Number  of 
EMM  Handles 

Return  the  number  of 
active  EMM  handles. 

AH  =  4BH 

AH  =  status 

BX  =  number  of  EMM 
handles,  if  AH  = 
OOH 

If  the  number  of  handles  returned  is  zero,  none  of  the 
expanded  memory  is  in  use.  The  number  of  active  EMM 
handles  never  exceeds  255. 

A  single  program  can  make  several  allocation  requests 
and  therefore  own  several  EMM  handles. 

Get  Pages 

Owned  by 
Handle 

Return  the  number 
of  logical  expanded 
memory  pages  allocated 

AH  =  4CH 

DX  =  EMM  handle 

AH  =  status 

BX  =  lexical  pages, 
ifAH  =  00H 

The  number  of  pages  returned  if  the  function  is  success¬ 
ful  is  always  in  the  range  1-512.  An  EMM  handle  never 
has  zero  pages  of  memory  allocated  to  it. 

to  a  specific  handle. 


*EMM  Functions  49H  and  4AH  (not  listed)  were  defined  in  EMS  version  3.0  and  are  “reserved”  in  later  EMS  versions. 


(more) 
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Function 

Name 

Action 

CaU 

With 

Returns 

Comments 

Get  Pages  for 

All  Handles 

Return  an  array  that 
contains  all  the  active 
handles  and  the  number 
of  logical  expanded 
memory  pages  associ¬ 
ated  with  each  handle. 

AH  =  4DH 

DI  =  offset  of  array 
to  receive 
information 

ES  =  array  segment 

AH  =  status 

BX  =  number  of  active 
EMM  handles 

IfAH  =  OOH,  array  is 
filled  in  as  described  in 
comments  column 

The  array  is  filled  in  with  doubleword  entries.  The  first 
word  of  each  entry  contains  a  handle;  the  second  word 
contains  the  number  of  pages  associated  with  that  handle. 
The  value  returned  in  BX  gives  the  number  of  valid 
doubleword  entries  in  the  array. 

Because  255  is  the  maximum  number  of  EMM  handles, 
the  array  need  not  be  larger  than  1020  bytes. 

Get/Set 

Page  Map 

Save  or  set  the  contents 
of  the  EMM  page¬ 
mapping  registers  on  the 
expanded  memory 
boards. 

AH  =  4EH 

AL  =  subfunction 
number 

DS:SI  =  array 
holding 
mapping 
information 
(Subfunc¬ 
tions 

AH  =  status 

AL  =  bytes  in  page¬ 
mapping  array 
(Subfunction  03H) 

Array  pointed  to  by 

ES:DI  receives  mapping 
information  for  Sub¬ 
functions  OOH  and  02H 

Subfunctions: 

OOH  =  get  mapping  registers  into  array 

OlH  =  set  mapping  registers  from  array 

02H  =  get  and  set  mapping  registers  in  one  operation 

03H  =  return  needed  size  of  page-mapping  array 

This  function  was  added  in  EMM  version  3.2  and  is 
designed  to  support  multitasking.  It  should  not  ordinarily 
be  used  by  application  programs. 

OlH,  02H) 
ES:DI  =  array  to 
receive  informa¬ 
tion  (Subfunc¬ 
tions  OOH,  02H) 

The  content  of  the  array  is  hardware  and  EMM  software 
dependent.  In  addition  to  the  contents  of  the  page¬ 
mapping  registers,  it  may  contain  other  information  that 
is  necessary  to  restore  the  expanded  memory  subsystem 
to  its  previous  state. 
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Table  9-3.  The  Expanded  Memory  Manager  (EMM)  Error  Codes. 


Error  Code  Significance 

OOH  Function  was  successful. 

SOH"  Internal  error  in  the  EMM  software.  Possible  causes  include  an  error  in  the 

driver  itself  or  damage  to  its  memory  image. 

81H  Malfunction  in  the  expanded  memory  hardware. 

82H  EMM  is  busy. 

83H  Invalid  expanded  memory  handle. 

84H  Function  requested  by  the  application  is  not  supported  by  the  EMM. 

85H  No  more  expanded  memory  handles  available. 

86H  Error  in  save  or  restore  of  mapping  context. 

87H  Allocation  request  specified  more  logical  pages  than  are  available  in  the 

system;  no  pages  were  allocated. 

88H  Allocation  request  specified  more  logical  pages  than  are  currently  avail¬ 

able  in  the  system  (the  request  does  not  exceed  the  physical  pages  that 
exist,  but  some  are  already  allocated  to  other  handles);  no  pages  were 
allocated. 

89H  Zero  pages  cannot  be  allocated. 

8AH  Logical  page  requested  for  mapping  is  outside  the  range  of  pages  assigned 

to  the  handle. 

8BH  Illegal  physical  page  number  in  mapping  request  (not  in  the  range  0-3). 

8CH  Save  area  for  mapping  contexts  is  full. 

8DH  Save  of  mapping  context  failed  because  save  area  already  contains  a  con¬ 

text  associated  with  the  requested  handle. 

8EH  Restore  of  mapping  context  failed  because  save  area  does  not  contain  a 

context  for  the  requested  handle. 

8FH  Subfunction  parameter  not  defined. 

An  application  program  that  uses  expanded  memory  should  regard  that  memory  as  a 
system  resource,  such  as  a  file  or  a  device,  and  use  only  the  documented  EMM  services  to 
allocate,  access,  and  release  expanded  memory  pages.  Here  is  the  general  strategy  that 
can  be  used  by  such  a  program: 

1 .  Establish  the  presence  of  the  EMM  by  one  of  the  two  methods  demonstrated  in 
Figures  9-6  and  9-7. 

2.  After  the  driver  is  known  to  be  present,  check  its  operational  status  with  EMM 
Function  40H. 

3.  Check  the  version  number  of  the  EMM  with  EMM  Function  46H  to  ensure  that  all  ser¬ 
vices  the  application  will  request  are  available. 

4.  Obtain  the  segment  of  the  page  frame  used  by  the  EMM  with  EMM  Function  41H. 

5.  Allocate  the  desired  number  of  expanded  memory  pages  with  EMM  Function  43H.  If 
the  allocation  is  successful,  the  EMM  returns  a  handle  in  DX  that  is  used  by  the  appli¬ 
cation  to  refer  to  the  expanded  memory  pages  it  owns.  This  step  is  exactly  analogous 
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to  opening  a  file  and  using  the  handle  obtained  from  the  open  function  for  subse¬ 
quent  read/write  operations  on  the  file. 

6.  If  the  requested  number  of  pages  is  not  available,  query  the  EMM  for  the  actual  num¬ 
ber  of  pages  available  (EMM  Function  42H)  and  determine  whether  the  program  can 
continue. 

7.  After  successfully  allocating  the  number  of  expanded  memory  pages  needed,  use 
EMM  Function  44H  to  map  logical  pages  in  and  out  of  the  physical  page  frame,  to  store 
and  retrieve  data  in  expanded  memory. 

8.  When  finished  using  the  expanded  memory  pages,  release  them  by  calling  EMM 
Function  45H.  Otherwise,  the  pages  will  not  be  available  for  use  by  other  programs 
until  the  system  is  restarted. 

A  program  skeleton  that  illustrates  this  general  approach  to  the  use  of  expanded  memory 

is  shown  in  Figure  9-8. 


mov 

ah,40h 

;  test 

EMM  status 

int 

67h 

or 

ah,  ah 

jnz 

error 

;  jump 

if  bad  status  from  EMM 

mov 

ah,46h 

;  check  EMM  version 

int 

67h 

or 

ah,  ah 

jnz 

error 

;  jump 

if  couldn't  get  version 

cmp 

al,30h 

;  make 

sure  at  least  ver.  3.0 

jb 

error 

;  jump 

if  wrong  EMM  version 

mov 

ah,41h 

;  get  page  frame  segment 

int 

67h 

or 

ah,  ah 

jnz 

error 

;  jump 

if  failed  to  get  frame 

mov 

page_f rame, bx 

;  save 

segment  of  page  frame 

mov 

ah,42h 

;  get  no.  of  available  pages 

int 

67h 

or 

ah,  ah 

jnz 

error 

/  jump 

if  get  pages  error 

mov 

total-pages, dx 

;  save 

total  EMM  pages 

mov 

avail_pages,bx 

/  save 

available  EMM  pages 

or 

bx,  bx 

jz 

error 

;  abort  if  no  pages  available 

mov 

ah,43h 

;  try  to  allocate  EMM  pages 

(more) 

Figure  9-8.  A  program  skeleton  for  the  use  of  expanded  memory.  This  code  assumes  that  the  presence  of  the 
Expanded  Memory  Manager  has  already  been  verified  with  one  of  the  techniques  shown  in  Figures  9-6 
and  9-7. 
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mov 

bx, needed—pages 

int 

67h 

if  allocation  is  successful 

or 

ah,  ah 

jnz 

error 

jump  if  allocation  failed 

mov 

emm_handle, dx 

save  handle  for  allocated  pages 

now  we  are  ready  for  other 
processing  using  EMM  pages 

map  in  EMM  memory  page  .  .  . 

mov 

bx, log_page 

BX  <-  EMM  logical  page  number 

mov 

al, phys_page 

AL  <-  EMM  physical  page  (0-3) 

mov 

dx, emm_handle 

EMM  handle  for  our  pages 

mov 

ah,44h  ; 

Fxn  44H  =  map  EMM  page 

int 

67h 

or 

ah,  ah 

jnz 

error  ; 

r  jump  if  mapping  error 

program  ready  to  terminate, 
give  up  allocated  EMM  pages  .  .  . 

mov 

dx,emm_handle 

handle  for  our  pages 

mov 

ah,45h 

EMM  Fxn  45H  =  release  pages 

int 

67h 

or 

ah,  ah 

jnz 

error  i 

r  jump  if  release  failed 

Figure  9-8.  Continued. 

An  interrupt  handler  or  resident  driver  that  uses  the  EMM  follows  the  same  general 
procedure  outlined  in  steps  1  through  8,  with  a  few  minor  variations.  It  may  need  to 
acquire  an  EMM  handle  and  allocate  pages  before  the  operating  system  is  fully  functional; 
in  particular,  the  MS-DOS  services  Open  File  or  Device  (Interrupt  21H  Function  3DH), 
lOCTL  (Interrupt  21H  Function  44H),  and  Get  Interrupt  Vector  (Interrupt  21H  Function 
35H)  cannot  be  assumed  to  be  available.  Thus,  such  a  handler  or  driver  must  use  a  mod¬ 
ified  version  of  the  “get  interrupt  vector”  technique  to  test  for  the  existence  of  the  EMM, 
fetching  the  contents  of  the  Interrupt  67H  vector  directly  instead  of  using  MS-DOS  Inter¬ 
rupt  21H  Function  35H. 

A  device  driver  or  interrupt  handler  typically  owns  its  expanded  memory  pages  on  a 
permanent  basis  (until  the  system  is  restarted)  and  never  deallocates  them.  Such  a  pro¬ 
gram  must  also  take  care  to  save  (EMM  Function  47H)  and  restore  (EMM  Function  48H) 
the  EMM’S  page-mapping  context  (the  EMM  pages  mapped  into  the  page  frame  at  the 
time  the  device  driver  or  interrupt  handler  takes  control  of  the  system)  so  that  use  of  the 
expanded  memory  by  a  foreground  program  will  not  be  disturbed. 
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The  EMM  relies  heavily  on  the  good  behavior  of  application  software  to  avoid  the  corrup¬ 
tion  of  expanded  memory.  If  several  applications  that  use  expanded  memory  are  running 
under  a  multitasking  manager,  such  as  Microsoft  Windows,  and  one  or  more  of  those  appli¬ 
cations  does  not  abide  strictly  by  the  EMM’s  conventions,  the  data  stored  in  expanded 
memory  can  be  corrupted. 


Extended  Memory 

Extended  memory  is  that  storage  at  addresses  above  1  MB  (lOOOOOH)  that  can  be  accessed 
by  an  80286  or  80386  microprocessor  running  in  protected  mode.  IBM  PC/AT-compatible 
machines  can  (theoretically)  have  as  much  as  15  MB  of  extended  memory  installed,  in 
addition  to  the  usual  1  MB  of  conventional  memory  address  space.  Unlike  expanded  mem¬ 
ory,  extended  memory  is  linearly  addressable:  The  address  of  each  memory  cell  is  fixed, 
so  no  special  manager  program  is  required. 

Protected-mode  operating  systems,  such  as  Microsoft  XENIX  and  MS  OS/2,  can  use  ex¬ 
tended  memory  for  execution  of  programs.  MS-DOS,  on  the  other  hand,  runs  in  real  mode 
on  an  80286  or  80386,  and  programs  running  under  its  control  cannot  ordinarily  execute 
from  extended  memory  or  even  address  that  memory  for  storage  of  data. 

To  provide  some  access  to  extended  memory  for  real-mode  programs,  IBM  PCAT- 
compatible  machines  contain  two  routines  in  their  ROM  BIOS  (Tables  9-4  and  9-5) 
that  allow  the  amount  of  extended  memory  present  to  be  determined  (Interrupt  15H  Func¬ 
tion  88H)  and  that  transfer  blocks  of  data  between  conventional  memory  and  extended 


Table  9-4.  IBM  PC/AT  ROM  BIOS  Interrupt  15H  Functions  for 
Access  to  Extended  Memory. 


Interrupt  15H  Function 

Call  With 

Returns 

Move  Extended  Memory  Block 

AH  =  87H* 

Carry  flag  =  0  if  successful 

CX  =  length  (words) 

1  if  error 

ES:SI  =  address  of  block 

AH  =  status: 

move  descriptor 

OOH  no  error 

table 

OlH  RAM  parity  error 
02H  exception  inter¬ 
rupt  error 

03H  gate  address  line 
20  failed 

Obtain  Size  of  Extended 

AH  =  88H 

AX  =  kilobytes  of  memory 

Memory 

installed  above  1  MB 

•Table  9-5  shows  the  descriptor  table  format  used  by  Function  87H. 
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memory  (Interrupt  15H  Function  87H).  These  routines  can  be  used  by  electronic  disks 
(RAMdisks)  and  by  other  programs  that  wish  to  use  extended  memory  for  fast  storage  and 
retrieval  of  information  that  would  otherwise  have  to  be  written  to  a  slower  physical  disk 
drive. 

Table  9-5.  Block  Move  Descriptor  Table  Format  for  IBM  PC/AT  ROM  BIOS 
Interrupt  15H  Function  87H  (Move  Extended  Memory  Block). 


Bytes  Contents 

OO-OFH  Zero 

10-llH  Segment  length  in  bytes  (2*CX- 1  or  greater) 
12-  14H  24-bit  source  address 

15H  Access  rights  byte  (93H) 

16-17H  Zero 

18-  19H  Segment  length  in  bytes  (2* CX- 1  or  greater) 

lA-  ICH  24-bit  destination  address 
IDH  Access  rights  byte  (93H) 

lE-lFH  Zero 

20-2FH  Zero 


Note:  This  data  structure  actually  constitutes  a  global  descriptor  table  (GDT)  to  be  used 
by  the  CPU  while  it  is  running  in  protected  mode;  the  zero  bytes  at  offsets  O-OFH  and 
20-2FH  are  filled  in  by  the  ROM  BIOS  code  before  the  mode  transition.  The  supplied  24- 
bit  address  is  a  linear  address  in  the  range  000000-FFFFFFH  (not  a  segment  and  offset), 
with  the  least  significant  byte  first  and  the  most  significant  byte  last. 

Programmers  should  use  these  ROM  BIOS  routines  with  caution.  Data  stored  in  extended 
memory  is  volatile;  it  is  lost  if  the  machine  is  turned  off.  The  transfer  of  data  to  or  from 
extended  memory  involves  a  switch  from  real  mode  to  protected  mode  and  back  again. 
This  is  a  relatively  slow  process  on  80286-based  machines;  in  some  cases  it  is  only  margin¬ 
ally  faster  than  actually  reading  the  data  from  a  fixed  disk.  In  addition,  programs  that  use 
the  ROM  BIOS  extended  memory  functions  are  not  compatible  with  the  MS-DOS  3.x  Com¬ 
patibility  Box  of  MS  OS/2,  nor  are  they  reliable  if  used  for  communications  or  networking. 

Finally,  a  major  deficit  in  these  ROM  BIOS  functions  is  that  they  do  not  make  any  attempt 
to  arbitrate  between  two  or  more  programs  or  device  drivers  that  are  using  extended 
memory  for  temporary  storage.  For  example,  if  an  application  program  and  an  installed 
RAMdisk  driver  attempt  to  put  data  in  the  same  area  of  extended  memory,  no  error  is 
returned  to  either  program,  but  the  data  belonging  to  one  or  both  may  be  destroyed. 

Figure  9-9  demonstrates  the  use  of  the  ROM  BIOS  routines  to  transfer  a  block  of  data  from 
extended  memory  to  conventional  memory. 
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;  block  move  descriptor  table 


bmdt 

db 

8 

dup 

(0) 

;  dummy  descriptor 

db 

8 

dup 

(0) 

;  GOT  descriptor 

db 

8 

dup 

(0) 

;  source  segment  descriptor 

db 

8 

dup 

(0) 

;  destination  segment  descriptor 

db 

8 

dup 

(0) 

;  BIOS  CS  segment  descriptor 

db 

8 

dup 

(0) 

;  BIOS  SS  segment  descriptor 

buff 

db 

8 Oh  dup  (0) 

;  buffer  to  receive  data 

mov 

dx,10h 

;  DX:AX  =  source  extended  memory 

mov 

ax,  0 

;  address  100000H  (1  MB) 

mov 

bx,seg  buff 

;  DS:BX  =  destination  conventional 

mov  • 

ds,bx 

;  memory  address 

mov 

bx, offset  buff 

mov 

cx, 80h 

;  CX  =  length  to  move  (bytes) 

mov 

si,seg  bmdt 

;  ES:SI  =  block  move  descriptor  table 

mov 

es,  si 

mov 

si, offset  bmdt 

call 

getblk 

;  get  block  from  extended  memory 

or 

ah,  ah 

;  test  status 

jnz 

error 

;  jump  if  block  move  failed 

getblk  proc 


mov 

mov 

mov 

mov 


near 


;  transfer  block  from  extended 
;  memory  to  real  memory 
;  call  with 

;  DX:AX  =  extended  memory  address 

;  DS:BX  =  destination  buffer 

;  CX  =  length  (bytes) 

;  ES:SI  =  block  move  descriptor  table 

;  returns 


;  AH  =  0  if  transfer  OK 
es : [ si+1 Oh] , CX  ;  store  length  in  descriptors 
es : [ si+1 8h] , cx 

;  store  access  rights  bytes 
byte  ptr  es : [ si+1 5h] , 93h 
byte  ptr  es : [ si+1 dh] , 93h 


(more) 

Figure  9-9.  Demonstration  of  a  block  move from  extended  memory  to  conventional  memory  using  the  ROM 
BIOS  routine.  The  procedure  gexbWs  accepts  a  source  address  in  extended  memory,  a  destination  address  in 
conventional  memory,  a  length  in  bytes,  and  the  segment  and  offset  of  a  block  move  descriptor  table.  The 
extended-memory  address  is  a  linear  32-bit  address,  of  which  only  the  lower  24  bits  are  significant;  the 
conventional-memory  address  is  a  segment  and  offset.  getblk  routine  converts  the  destination  segment 

and  offset  to  a  linear  address,  builds  the  appropriate  fields  in  the  block  move  descriptor  table,  invokes  the  ROM 
BIOS  routine  to  perform  the  transfer,  and  returns  the  status  in  the  AH  register. 
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;  source  (extended  memory)  address 


mov 

es : [si+1 2h] , ax 

mov 

es: [si+1 4h] ,dl 

;  destination  (conv  memory)  address 

mov 

ax,  ds 

;  segment  *  1 6 

mov 

dx,  1  6 

mul 

dx 

add 

ax,  bx 

;  +  offset  ->  linear  address 

adc 

dx,  0 

mov 

es : [si+1 ah] , ax 

mov 

es : [si+1 ch] , dl 

shr 

cx,  1 

;  convert  length  to  words 

mov 

ah,87h 

;  Fxn  87H  =  block  move 

int 

15h 

;  transfer  to  ROM  BIOS 

ret 

;  back  to  caller 

Figure  9-9.  Continued. 


Summary 

Personal  computers  that  run  MS-DOS  can  support  as  many  as  three  different  types  of  fast, 
random-access  memory  (RAM).  Each  type  has  specific  characteristics  and  requires  differ¬ 
ent  techniques  for  its  management. 

Conventional  memory  is  the  term  used  for  the  1  MB  of  linear  address  space  that  can  be  ac¬ 
cessed  by  an  8086  or  8088  microprocessor  or  by  an  80286  or  80386  microprocessor  run¬ 
ning  in  real  mode.  MS-DOS  and  the  programs  that  execute  under  its  control  run  in  this 
address  space.  MS-DOS  provides  application  programs  with  services  to  dynamically  allo¬ 
cate  and  release  blocks  of  conventional  memory. 

As  much  as  8  MB  of  expanded  memory  can  be  installed  in  a  PC  and  used  for  electronic 
disks,  disk  caching,  and  storage  of  application  program  data.  The  memory  is  made  avail¬ 
able  in  16  KB  pages  and  is  administered  by  a  driver  program  called  the  Expanded  Memory 
Manager,  which  provides  allocation,  mapping,  deallocation,  and  multitasking  support. 

Extended  memory  refers  to  the  memory  at  addresses  above  1  MB  that  can  be  accessed  by 
an  80286-based  or  80386-based  microprocessor  running  in  protected  mode;  it  is  not  avail¬ 
able  in  PCs  based  on  the  8086  or  8088  microprocessors.  As  much  as  15  MB  of  extended 
memory  can  be  installed;  however,  the  ROM  BIOS  services  to  access  the  memory  are 
primitive  and  slow,  and  no  manager  is  provided  to  arbitrate  between  multiple  programs 
that  attempt  to  use  the  same  extended  memory  addresses  for  storage. 


Ray  Duncan 
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Article  10 

The  MS-DOS  EXEC  Function 


The  MS-DOS  system  loader,  which  brings  .COM  or  .EXE  files  from  disk  into  memory  and 
executes  them,  can  be  invoked  by  any  program  with  the  MS-DOS  EXEC  function  (Inter¬ 
rupt  21H  Function  4BH).  The  default  MS-DOS  command  interpreter,  COMMAND.COM, 
uses  the  EXEC  function  to  load  and  run  its  external  commands,  such  as  CHKDSK,  as  well 
as  other  application  programs.  Many  popular  commercial  programs,  such  as  databases  and 
word  processors,  use  EXEC  to  load  and  run  subsidiary  programs  (spelling  checkers,  for 
example)  or  to  load  and  run  a  second  copy  of  COMMAND.COM.  This  allows  a  user  to  run 
subsidiary  programs  or  enter  MS-DOS  commands  without  losing  his  or  her  current 
working  context. 

When  EXEC  is  used  by  one  program  (called  the  parent)  to  load  and  run  another  (called 
the  child),  the  parent  can  pass  certain  information  to  the  child  in  the  form  of  a  set  of  strings 
called  the  environment,  a  command  line,  and  two  file  control  blocks.  The  child  program 
also  inherits  the  parent  program’s  handles  for  the  MS-DOS  standard  devices  and  for  any 
other  files  or  character  devices  the  parent  has  opened  (unless  the  open  operation  was  per¬ 
formed  with  the  “noninheritance”  option).  Any  operations  performed  by  the  child  on 
inherited  handles,  such  as  seeks  or  file  I/O,  also  affect  the  file  pointers  associated  with  the 
parent’s  handles.  A  child  program  can,  in  turn,  load  another  program,  and  the  cycle  can  be 
repeated  until  the  system’s  memory  area  is  exhausted. 

Because  MS-DOS  is  not  a  multitasking  operating  system,  a  child  program  has  complete 
control  of  the  system  until  it  has  finished  its  work;  the  parent  program  is  suspended.  This 
type  of  processing  is  sometimes  called  synchronous  execution.  When  the  child  termi¬ 
nates,  the  parent  regains  control  and  can  use  another  system  function  call  (Interrupt  21H 
Function  4DH)  to  obtain  the  child’s  return  code  and  determine  whether  the  program  ter¬ 
minated  normally,  because  of  a  critical  hardware  error,  or  because  the  user  entered  a 
Control-C. 

In  addition  to  loading  a  child  program,  EXEC  can  also  be  used  to  load  subprograms  and 
overlays  for  application  programs  written  in  assembly  language  or  in  a  high-level  language 
that  does  not  include  an  overlay  manager  in  its  run-time  library.  Such  overlays  typically 
cannot  be  run  as  self-contained  programs;  most  require  “helper”  routines  or  data  in  the 
application’s  root  segment. 

The  EXEC  function  is  available  only  with  MS-DOS  versions  2.0  and  later.  With  MS-DOS 
versions  1.x,  a  parent  program  can  use  Interrupt  21H  Function  26H  to  create  a  program 
segment  prefix  for  a  child  but  must  carry  out  the  loading,  relocation,  and  execution  of  the 
child’s  code  and  data  itself,  without  any  assistance  from  the  operating  system. 
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How  EXEC  Works 

When  the  EXEC  function  receives  a  request  to  execute  a  program,  it  first  attempts  to  locate 
and  open  the  specified  program  file.  If  the  file  cannot  be  found,  EXEC  fails  immediately 
and  returns  an  error  code  to  the  caller. 

If  the  file  exists,  EXEC  opens  the  file,  determines  its  size,  and  inspects  the  first  block  of  the 
file.  If  the  first  2  bytes  of  the  block  are  the  ASCII  characters  AfZ,  the  file  is  assumed  to  con¬ 
tain  a  .EXE  load  module,  and  the  sizes  of  the  program’s  code,  data,  and  stack  segments  are 
obtained  from  the  .EXE  file  header.  Otherwise,  the  entire  file  is  assumed  to  be  an  absolute 
load  image  (a  .COM  program).  The  actual  filename  extension  (.COM  or  .EXE)  is  ignored 
in  this  determination. 

At  this  point,  the  amount  of  memory  needed  to  load  the  program  is  known,  so  EXEC 
attempts  to  allocate  two  blocks  of  memory:  one  to  hold  the  new  program’s  environment 
and  one  to  contain  the  program’s  code,  data,  and  stack  segments.  Assuming  that  enough 
memory  is  available  to  hold  the  program  itself,  the  amount  actually  allocated  to  the  pro¬ 
gram  varies  with  its  type.  Programs  of  the  .COM  type  are  usually  given  all  the  free  mem¬ 
ory  in  the  system  (unless  the  memory  area  has  previously  become  fragmented),  whereas 
the  amount  assigned  to  a  .EXE  program  is  controlled  by  two  fields  in  the  file  header, 
MINALLOC  and  MAXALLOC,  that  are  set  by  the  Microsoft  Object  Linker  (LINK).  See 
PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Structure 
of  an  Application  Program;  Programming  Tools:  The  Microsoft  Object  Linker;  PROGRAM¬ 
MING  UTILITIES:  link. 

EXEC  then  copies  the  environment  from  the  parent  into  the  memory  allocated  for  child’s 
environment,  builds  a  program  segment  prefix  (PSP)  at  the  base  of  the  child’s  program 
memory  block,  and  copies  into  the  child’s  PSP  the  command  tail  and  the  two  default  file 
control  blocks  passed  by  the  parent.  The  previous  contents  of  the  terminate  (Interrupt 
22H),  Control-C  (Interrupt  23H),  and  critical  error  (Interrupt  24H)  vectors  are  saved  in  the 
new  PSP,  and  the  terminate  vector  is  updated  so  that  control  will  return  to  the  parent 
program  when  the  child  terminates  or  is  aborted. 

The  actual  code  and  data  portions  of  the  child  program  are  then  read  from  the  disk  file 
into  the  program  memory  block  above  the  newly  constructed  PSP.  If  the  child  is  a  .EXE 
program,  a  relocation  table  in  the  file  header  is  used  to  fix  up  segment  references  within 
the  program  to  reflect  its  actual  load  address. 

Finally,  the  EXEC  function  sets  up  the  CPU  registers  and  stack  according  to  the  program 
type  and  transfers  control  to  the  program.  The  entry  point  for  a  .COM  file  is  always  offset 
lOOH  within  the  program  memory  block  (the  first  byte  following  the  PSP).  The  entry  point 
for  a  .EXE  file  is  specified  in  the  file  header  and  can  be  anywhere  within  the  program.  See 
also  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos: 
Structure  of  an  Application  Program. 

When  EXEC  is  used  to  load  and  execute  an  overlay  rather  than  a  child  program,  its  opera¬ 
tion  is  much  simpler  than  described  above.  For  an  overlay,  EXEC  does  not  attempt  to  allo¬ 
cate  memory  or  build  a  PSP  or  environment.  It  simply  loads  the  contents  of  the  file  at  the 
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address  specified  by  the  calling  program  and  performs  any  necessary  relocations  (if  the 
overlay  file  has  a  .EXE  header),  using  a  segment  value  that  is  also  supplied  by  the  caller. 
EXEC  then  returns  to  the  program  that  invoked  it,  rather  than  transferring  control  to  the 
code  in  the  newly  loaded  file.  The  requesting  program  is  responsible  for  calling  the 
overlay  at  the  appropriate  location. 


Using  EXEC  to  Load  a  Program 

When  one  program  loads  and  executes  another,  it  must  follow  these  steps: 

1.  Ensure  that  enough  free  memory  is  available  to  hold  the  code,  data,  and  stack  of  the 
child  program. 

2.  Set  up  the  information  to  be  passed  to  EXEC  and  the  child  program. 

3.  Call  the  MS-DOS  EXEC  function  to  run  the  child  program. 

4.  Recover  and  examine  the  child  program’s  termination  and  return  codes. 

Making  memory  available 

MS-DOS  typically  allocates  all  available  memory  to  a  .COM  or  .EXE  program  when  it  is 
loaded.  (The  infrequent  exceptions  to  this  rule  occur  when  the  transient  program  area 
is  fragmented  by  the  presence  of  resident  data  or  programs  or  when  a  .EXE  program  is 
loaded  that  was  linked  with  the  /CPARMAXALLOC  switch  or  modified  with  EXEMOD.) 
Therefore,  before  a  program  can  load  another  program,  it  must  free  any  memory  it  does 
not  need  for  its  own  code,  data,  and  stack. 

The  extra  memory  is  released  with  a  call  to  the  MS-DOS  Resize  Memory  Block  function 
(Interrupt  21H  Function  4AH).  In  this  case,  the  segment  address  of  the  parent’s  PSP  is 
passed  in  the  ES  register,  and  the  BX  register  holds  the  number  of  paragraphs  of  memory 
the  program  must  retain  for  its  own  use.  If  the  prospective  parent  is  a  .COM  program,  it 
must  be  certain  to  move  its  stack  to  a  safe  area  if  it  is  reducing  its  memory  allocation  to  less 
than  64  KB. 

Preparing  parameters  for  EXEC 

When  used  to  load  and  execute  a  program,  the  EXEC  function  must  be  supplied  with  two 
principal  parameters: 

•  The  address  of  the  child  program’s  pathname 

•  The  address  of  a  parameter  block 

The  parameter  block,  in  turn,  contains  the  addresses  of  information  to  be  passed  to  the 
child  program. 

The  program  name 

The  pathname  for  the  child  program  must  be  an  unambiguous,  null-terminated  (ASCIIZ) 
file  specification  (no  wildcard  characters).  If  a  path  is  not  included,  the  current  directory  is 
searched  for  the  program;  if  a  drive  specifier  is  not  present,  the  default  drive  is  used. 
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The  parameter  block 

The  parameter  block  contains  the  addresses  of  four  data  items  (Figure  10-1): 

•  The  environment  block 

•  The  command  tail 

•  The  two  default  file  control  blocks  (FCBs) 

The  position  reserved  in  the  parameter  block  for  the  pointer  to  an  environment  is  only 
2  bytes  and  contains  a  segment  address,  because  an  environment  is  always  paragraph 
aligned  (its  address  is  always  evenly  divisible  by  l6);  a  value  of  OOOOH  indicates  the  parent 
program’s  environment  should  be  inherited  unchanged.  The  remaining  three  addresses 
are  all  doubleword  addresses  in  the  standard  Intel  format,  with  an  offset  value  in  the  lower 
word  and  a  segment  value  in  the  upper  word. 


ToCaU 

AH 

=  4BH 

AL 

=  OOH  load  and  execute  child  process 

03H  load  overlay 

DS:DX 

=  segment:offset  of  ASCIIZ  pathname  for  an  executable  program  file 

ES:BX 

=  segment:offset  of  parameter  block 

Returns 

If  Function  is  successful: 

Carry  flag  is  clear. 

Other  registers  are  preserved  if  MS-DOS  version  3.0  or  later,  destroyed  if  MS-DOS 
versions  2.x. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX 

=  error  code 

Parameter  Block  Format 

Offset 

Contents 

IfAL  = 

OOH  (load  and  execute  program): 

OOH 

Segment  pointer  of  the  environment  to  be  passed 

02H 

Offset  of  command-line  tail  for  the  new  PSP 

04H 

Segment  of  command-line  tail  for  the  new  PSP 

06H 

Offset  of  first  file  control  block,  to  be  copied  into  new  PSP  at  offset  5CH 

OSH 

Segment  of  first  file  control  block 

OAH 

Offset  of  second  file  control  block,  to  be  copied  into  new  PSP  at  offset  6CH 

OCH 

Segment  of  second  file  control  block 

IfAL  = 

03H  (load  overlay): 

OOH 

Segment  address  where  overlay  is  to  be  loaded 

02H 

Relocation  factor  to  apply  to  loaded  image 

Figure  10-1.  Synopsis  of  calling  conventions for  the  MS-DOS  EXEC function  (Interrupt  21H  Function  4BH), 
which  can  he  used  to  load  and  execute  child  processes  or  overlays. 
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The  environment 

An  environment  always  begins  on  a  paragraph  boundary  and  is  composed  of  a  series  of 
null-terminated  (ASCII2)  strings  of  the  form: 

name^variable 

The  end  of  the  entire  set  of  strings  is  indicated  by  an  additional  null  byte. 

If  the  environment  pointer  in  the  parameter  block  supplied  to  an  EXEC  call  contains  zero, 
the  child  simply  acquires  a  copy  of  the  parent’s  environment.  The  parent  can,  however, 
provide  a  segment  pointer  to  a  different  or  expanded  set  of  strings.  In  either  case,  under 
MS-DOS  versions  3.0  and  later,  EXEC  appends  the  child  program’s  fully  qualified  path¬ 
name  to  its  environment  block.  The  maximum  size  of  an  environment  is  32  KB,  so  very 
large  amounts  of  information  can  be  passed  between  programs  by  this  mechanism. 

The  original,  or  master,  environment  for  the  system  is  owned  by  the  command  processor 
that  is  loaded  when  the  system  is  turned  on  or  restarted  (usually  COMMAND.COM). 
Strings  are  placed  in  the  system’s  master  environment  by  COMMAND.COM  as  a  result  of 
PATH,  SHELL,  PROMPT,  and  SET  commands,  with  default  values  always  present  for  the 
first  two.  For  example,  if  an  MS-DOS  version  3.2  system  is  started  from  drive  C  and  a  PATH 
command  is  not  present  in  the  AUTOEXEC.BAT  file  nor  a  SHELL  command  in  the 
CONFIG.SYS  file,  the  master  environment  will  contain  the  two  strings: 

PATH= 

COMSPEC=C:\COMMAND.COM 

These  specifications  are  used  by  COMMAND.COM  to  search  for  executable  “external” 
commands  and  to  find  its  own  executable  file  on  the  disk  so  that  it  can  reload  its  transient 
portion  when  necessary.  When  the  PROMPT  string  is  present  (as  a  result  of  a  previous 
PROMPT  or  SET  PROMPT  command),  COMMAND.COM  uses  it  to  tailor  the  prompt  dis¬ 
played  to  the  user. 


0123456789 
0000  43  4F  4D  53  50  45  43  3D  43  3A 
0010  4E  44  2E  43  4F  4D  00  50  52  4F 
0020  24  5F  24  64  20  20  20  24.  74  24 
0030  68  24  68  24  68  20  24  71  24  71 
0040  48  3D  43  3A  5C  53  59  53  54  45 
0050  53  4D  3B  43  3A  5C  57  53  3B  43 
0060  52  4E  45  54  3B  43  3A  5C  46  4F 
0070  33  31  3B  00  00  01  00  43  3A  5C 
0080  50  43  33  31  5C  46  4F  52  54  48 


A  B  C  D  E  F  0123456789ABCDEF 
5C  43  4F  4D  4D  41  C0MSPEC=C : \C0MMA 
4D  50  54  3D  24  70  ND . COM. PROMPT=$p 
68  24  68  24  68  24  $_$d  $t$h$h$h$ 
24  67  00  50  41  54  h$h$h  $q$q$g.PAT 
4D  3B  43  3A  5C  41  H=C: \SYSTEM;C: \A 
3A  5C  45  54  48  45  SM;C:  \WS;C; \ETHE 
52  54  48  5C  50  43  RNET; C : \FORTH\PC 
46  4F  52  54  48  5C  31 ; . . . . C : \FORTH\ 
2E  43  4F  4D  00  PC31 \FORTH . COM. 


Figure  10-2.  Dump  of  a  typical  environment  under  MS-DOS  version  3.2.  This  particular  example  contains 
the  default  COMSPEC parameter  and  two  relatively  complex  PATH  and  PROMPT  control  strings  that  were  set 
up  by  entries  in  the  user’s  AUTOEXEC  file.  Note  the  two  null  bytes  at  offset  73H,  which  indicate  the  end  of  the 
environment.  These  bytes  are followed  by  the  pathname  of  the  program  that  owns  the  environment. 
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Other  strings  in  the  environment  are  used  only  for  informational  purposes  by  transient 
programs  and  do  not  affect  the  operation  of  the  operating  system  proper.  For  example, 
the  Microsoft  C  Compiler  and  the  Microsoft  Object  Linker  look  in  the  environment  for 
INCLUDE,  LIB,  and  TMP  strings  that  specify  the  location  of  include  files,  library  files,  and 
temporary  working  files.  Figure  10-2  contains  a  hex  dump  of  a  typical  environment  block. 

The  command  tail 

The  command  tail  to  be  passed  to  the  child  program  takes  the  form  of  a  byte  indicating 
the  length  of  the  remainder  of  the  command  tail,  followed  by  a  string  of  ASCII  characters 
terminated  with  an  ASCII  carriage  return  (ODH);  the  carriage  return  is  not  included  in  the 
length  byte.  The  command  tail  can  include  switches,  filenames,  and  other  parameters  that 
can  be  inspected  by  the  child  program  and  used  to  influence  its  operation.  It  is  copied 
into  the  child  program’s  PSP  at  offset  80H. 

When  COMMAND.COM  uses  EXEC  to  run  a  program,  it  passes  a  command  tail  that 
includes  everything  the  user  typed  in  the  command  line  except  the  name  of  the  program 
and  any  redirection  parameters.  I/O  redirection  is  processed  within  COMMAND.COM 
itself  and  is  manifest  in  the  behavior  of  the  standard  device  handles  that  are  inherited 
by  the  child  program.  Any  other  program  that  uses  EXEC  to  run  a  child  program  must  try 
to  perform  any  necessary  redirection  on  its  own  and  must  supply  an  appropriate  com¬ 
mand  tail  so  that  the  child  program  will  behave  as  though  it  had  been  loaded  by 
COMMAND.COM. 

The  default  file  control  blocks 

The  two  default  FCBs  pointed  to  by  the  EXEC  parameter  block  are  copied  into  the  child 
program’s  PSP  at  offsets  5CH  and  6CH.  See  also  PROGRAMMING  IN  THE  MS-DOS 
ENVIRONMENT:  Programming  for  ms-dos:  File  and  Record  Management. 

Few  of  the  currently  popular  application  programs  use  FCBs  for  file  and  record  I/O 
because  FCBs  do  not  support  the  hierarchical  directory  structure.  But  some  programs  do 
inspect  the  default  FCBs  as  a  quick  way  to  isolate  the  first  two  switches  or  other  parame¬ 
ters  from  the  command  tail.  Therefore,  to  make  its  own  identity  transparent  to  the  child 
program,  the  parent  should  emulate  the  action  of  COMMAND.COM  by  parsing  the  first 
two  parameters  of  the  command  tail  into  the  default  FCBs.  This  can  be  conveniently  ac¬ 
complished  with  the  MS-DOS  function  Parse  Filename  (Interrupt  21H  Function  29H). 

If  the  child  program  does  not  require  one  or  both  of  the  default  FCBs,  the  corresponding 
address  in  the  parameter  block  can  be  initialized  to  point  to  two  dummy  FCBs  in  the  appli¬ 
cation’s  memory  space.  These  dummy  FCBs  should  consist  of  1  zero  byte  followed  by  11 
bytes  containing  ASCII  blank  characters  (20H). 
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Running  the  child  program 

After  the  parent  program  has  constructed  the  necessary  parameters,  it  can  invoke  the 
EXEC  function  by  issuing  Interrupt  21H  with  the  registers  set  as  follows: 

AH  =  4BH 

AL  =  OOH  (EXEC  subfunction  to  load  and  execute  program) 

DS:DX  =  segment:offset  of  program  pathname 

ES:BX  =  segmentioffset  of  parameter  block 

Upon  return  from  the  software  interrupt,  the  parent  must  test  the  carry  flag  to  determine 
whether  the  child  program  did,  in  fact,  run.  If  the  carry  flag  is  clear,  the  child  program  was 
successfully  loaded  and  given  control.  If  the  carry  flag  is  set,  the  EXEC  function  failed,  and 
the  error  code  returned  in  AX  can  be  examined  to  determine  why.  The  usual  reasons  are 

•  The  specified  file  could  not  be  found. 

•  The  file  was  found,  but  not  enough  memory  was  free  to  load  it. 

Other  causes  are  uncommon  and  can  be  symptoms  of  more  severe  problems  in  the 
system  as  a  whole  (such  as  damage  to  disk  files  or  to  the  memory  image  of  MS-DOS).  With 
MS-DOS  versions  3  0  and  later,  additional  details  about  the  cause  of  an  EXEC  failure  can 
be  obtained  by  subsequently  calling  Interrupt  21H  Function  59H  (Get  Extended  Error 
Information). 

In  general,  supplying  either  an  invalid  address  for  an  EXEC  parameter  block  or  invalid 
addresses  within  the  parameter  block  itself  does  not  cause  a  failure  of  the  EXEC  function, 
but  may  result  in  the  child  program  behaving  in  unexpected  ways. 

Special  considerations 

With  MS-DOS  versions  2.x,  the  previous  contents  of  all  the  parent  registers  except  for  CS:IP 
can  be  destroyed  after  an  EXEC  call,  including  the  stack  pointer  in  SS:SP.  Consequently, 
before  issuing  the  EXEC  call,  the  parent  must  push  onto  the  stack  the  contents  of  any  regis¬ 
ters  that  it  needs  to  preserve,  and  then  it  must  save  the  stack  segment  and  offset  in  a  loca¬ 
tion  that  is  addressable  with  the  CS  segment  register.  Upon  return,  the  stack  segment  and 
offset  can  be  loaded  into  SS:SP  with  code  segment  overrides,  and  then  the  other  registers 
can  be  restored  by  popping  them  off  the  stack.  With  MS-DOS  versions  3.0  and  later,  regis¬ 
ters  are  preserved  across  an  EXEC  call  in  the  usual  fashion. 

Note:  The  code  segments  of  Windows  applications  that  use  this  technique  should  be 
given  the  IMPURE  attribute. 

In  addition,  a  bug  in  MS-DOS  version  2.0  and  in  PC-DOS  versions  2.0  and  2.1  causes  an 
arbitrary  doubleword  in  the  parent’s  stack  segment  to  be  destroyed  during  an  EXEC  call. 
When  the  parent  is  a  .COM  program  and  SS  =  PSP,  the  damaged  location  falls  within  the 
PSP  and  does  no  harm;  however,  in  the  case  of  a  .EXE  parent  where  DS  =  SS,  the  affected 
location  may  overlap  the  data  segment  and  cause  aberrant  behavior  or  even  a  crash  after 
the  return  from  EXEC.  This  bug  was  fixed  in  MS-DOS  versions  2.11  and  later  and  in 
PC-DOS  versions  3*0  and  later. 
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Examining  the  child  program’s  return  codes 

If  the  EXEC  function  succeeds,  the  parent  program  can  call  Interrupt  21H  Function  4DH 
(Get  Return  Code  of  Child  Process)  to  learn  whether  the  child  executed  normally  to  com¬ 
pletion  and  passed  back  a  return  code  or  was  terminated  by  the  operating  system  because 
of  an  external  event.  Function  4DH  returns 

AH  =  termination  type: 

OOH  Child  terminated  normally  (that  is,  exited  via  Interrupt  20H  or  Interrupt 

21H  Function  OOH  or  Function  4CH). 

OlH  Child  was  terminated  by  user’s  entry  of  a  Ctrl-C. 

02H  Child  was  terminated  by  critical  error  handler  (either  the  user  responded 
with  A  to  the  Abort,  Retry,  Ignore  prompt  from  the  system’s  default  Inter¬ 
rupt  24H  handler,  or  a  custom  Interrupt  24H  handler  returned  to  MS-DOS 
with  action  code  =  02H  in  register  AL). 

03H  Child  terminated  normally  and  stayed  resident  (that  is,  exited  via  Interrupt 
21H  Function  31H  or  Interrupt  27H). 

AL  =  return  code: 

Value  passed  by  the  child  program  in  register  AL  when  it  terminated  with  Interrupt 
21H  Function  4CH  or  31H. 

OOH  if  the  child  terminated  using  Interrupt  20H,  Interrupt  27H,  or  Interrupt  21H 
Function  OOH. 

These  values  are  only  guaranteed  to  be  returned  once  by  Function  4DH.  Thus,  a  subse¬ 
quent  call  to  Function  4DH,  without  an  intervening  EXEC  call,  does  not  necessarily  return 
any  useful  information.  Additionally,  if  Function  4DH  is  called  without  a  preceding  suc¬ 
cessful  EXEC  call,  the  returned  values  are  meaningless. 

Using  COMMAND.COM  with  EXEC 

An  application  program  can  “shell”  to  MS-DOS — that  is,  provide  the  user  with  an  MS-DOS 
prompt  without  terminating — by  using  EXEC  to  load  and  execute  a  secondary  copy  of 
COMMAND.COM  with  an  empty  command  tail.  The  application  can  obtain  the  location  of 
the  COMMAND.COM  disk  file  by  inspecting  its  own  environment  for  the  COMSPEC  string. 
The  user  returns  to  the  application  from  the  secondary  command  processor  by  typing  exit 
at  the  COMMAND.COM  prompt. 

Batch-file  interpretation  is  carried  out  by  COMMAND.COM,  and  a  batch  (.BAT)  file  can¬ 
not  be  called  using  the  EXEC  function  directly.  Similarly,  the  sequential  search  for  .COM, 
.EXE,  and  .BAT  files  in  all  the  locations  specified  in  the  environment’s  PATH  variable  is  a 
function  of  COMMAND.COM,  rather  than  of  EXEC.  To  execute  a  batch  file  or  search  the 
system  path  for  a  program,  an  application  program  can  use  EXEC  to  load  and  execute  a 
secondary  copy  of  COMMAND.COM  to  use  as  an  intermediary.  The  application  finds  the 
location  of  COMMAND.COM  as  described  in  the  preceding  paragraph,  but  it  passes  a 
command  tail  in  the  form: 

/C  program  parameterl  parameter2 . . . 
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where  program  is  the  .EXE,  .COM,  or  .BAT  file  to  be  executed.  When  program  termi¬ 
nates,  the  secondary  copy  of  COMMAND.COM  exits  and  returns  control  to  the  parent. 

A  parent  and  child  example 

The  source  programs  PARENT.ASM  in  Figure  10-3  and  CHILD.ASM  in  Figure  10-4  illustrate 
how  one  program  uses  EXEC  to  load  another. 

name  parent 

title  'PARENT  demonstrate  EXEC  call' 

;  PARENT.EXE  -  demonstration  of  EXEC  to  run  process 

;  Uses  MS-DOS  EXEC  (Int  21 H  Function  4BH  Subfunction  OOH) 

;  to  load  and  execute  a  child  process  named  CHILD.EXE, 

;  then  displays  CHILD'S  return  code. 

;  Ray  Duncan,  June  1987 


stdin 

equ 

0 

;  standard  input 

stdout 

equ 

1 

;  standard  output 

stderr 

equ 

2 

;  standard  error 

stksize 

equ 

128 

;  size  of  stack 

cr 

equ 

Odh 

;  ASCII  carriage  return 

If 

equ 

Oah 

;  ASCII  linefeed 

DGROUP 

group 

_DATA,_ENVIR 

, -STACK 

-TEXT 

segment 

byte  public 

' CODE ' 

;  executable  code  segment 

assume 

cs:_TEXT,ds: 

—DATA, ss : 

; -STACK 

stk_seg 

dw 

7 

;  original  SS  contents 

stk_ptr 

dw 

7 

;  original  SP  contents 

main 

proc 

far 

;  entry  point  from  MS-DOS 

mov 

ax , -DATA 

;  set  DS  =  our  data  segment 

mov 

ds,  ax 

;  now  give  back  extra  memory 
;  so  child  has  somewhere  to  run... 

Figure  10-3.  PARENT.ASM,  source  code  for  PARENT.EXE.  (more) 
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mov 

ax,  es 

mov 

bx,  ss 

sub 

bx,  ax 

add 

bx, stksize/1 6 

mov 

ah, 4ah 

int 

21h 

jc 

maini 

mov 

dx, offset  DGROUP rmsgl 

mov 

cx,msg1_len 

call 

pmsg 

push 

ds 

mov 

stk_seg, ss 

mov 

stk_ptr, sp 

mov  ax,ds 

mov  es,ax 

mov  dx, offset  DGROUP rename 

mov  bx, offset  DGROUP: pars 

mov  ax,4b00h 

int  21 h 

cli 

mov  ss,stk_seg 

mov  sp,stk_ptr 

sti 

pop  ds 

jc  main2 


mov 

ah, 4dh 

int 

21h 

xchg 

al,  ah 

mov 

bx, offset 

DGROUP  rmsg4 a 

call 

b2hex 

mov 

al,  ah 

mov 

bx, offset 

DGROUP rmsg4b 

call 

b2hex 

mov 

dx, offset 

DGROUP :msg4 

mov 

cx,msg4_len 

call 

pmsg 

mov 

ax, 4c00h 

int 

21h 

Figure  10-3.  Continued. 


;  let  AX  =  segment  of  PSP  base 
;  and  BX  =  segment  of  stack  base 
;  reserve  seg  stack  -  seg  psp 
;  plus  paragraphs  of  stack 
;  fxn  4 AH  =  modify  memory  block 

;  display  parent  message  ... 

;  DSrDX  =  address  of  message 
;  CX  =  length  of  message 

;  save  parent's  data  segment 
;  save  parent's  stack  pointer 

;  now  EXEC  the  child  process... 

;  set  ES  =  DS 

;  DSrDX  =  child  pathname 
;  ESrBX  =  parameter  block 
;  function  4BH  subfunction  OOH 
;  transfer  to  MS-DOS 

;  (for  bug  in  some  early  8088s) 

;  restore  parent's  stack  pointer 

;  (for  bug  in  some  early  8088s) 

;  restore  DS  =  our  data  segment 

;  jump  if  EXEC  failed 

;  otherwise  EXEC  succeeded, 

;  convert  and  display  child's 
;  termination  and  return  codes . . . 
;  fxn  4DH  =  get  return  code 
;  transfer  to  MS-DOS 
;  convert  termination  code 


;  get  back  return  code 
;  and  convert  it 

;  DSrDX  =  address  of  message 
;  CX  =  length  of  message 
;  display  it 

;  no  error,  terminate  program 
;  with  return  code  =  0 


(more) 
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maini : 

mov 

bx, offset 

DGROUP :msg2a 

; 

convert  error  code 

call 

b2hex 

mov 

dx, offset 

DGROUP : msg2 

f 

display  message  'Memory 

mov 

cx,msg2_len 

; 

resize  failed. . . ' 

call 

pmsg 

jmp 

main3 

main2 : 

mov 

bx, offset 

DGROUP :msg3a 

• 

convert  error  code 

call 

b2hex 

mov 

dx, offset 

DGROUP :msg3 

; 

display  message  'EXEC 

mov 

cx,msg3_len 

; 

call  failed. . . ' 

call 

pmsg 

mainS : 

mov 

ax, 4c01 h 

; 

error,  terminate  program 

int 

21h 

with  return  code  =  1 

main 

endp 

end  of  main  procedure 

b2hex 

proc 

near 

. 

convert  byte  to  hex  ASCII 

; 

call  with  AL  =  binary  value 

; 

BX  =  addr  to  store 

push 

ax 

shr 

al,  1 

shr 

al,  1 

shr 

al,  1 

shr 

al,1 

call 

ascii 

/ 

become  first  ASCII  character 

mov 

[bx] , al 

; 

store  it 

pop 

ax 

and 

al,0fh 

; 

isolate  lower  4  bits,  which 

call 

ascii 

; 

become  the  second  ASCII  chare 

mov 

[bx+1 ] , al 

/ 

store  it 

ret 

b2hex 

endp 

ascii 

proc 

near 

. 

convert  value  OO-OFH  in  AL 

add 

al, 'O' 

; 

into  a  "hex  ASCII"  character 

cmp 

al, '9' 

jle 

ascii2 

; 

jump  if  in  range  00-09H, 

add 

al, 'A'-'9' 

>1 

offset  it  to  range  OA-OFH, 

ascii2 : 

ret 

• 

return  ASCII  char,  in  AL 

ascii 

endp 

pmsg 

proc 

near 

; 

displays  message  on  standard 

call  with  DS:DX  =  address, 
CX  =  length 


Figure  10-3.  Continued. 
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mov 

bx, stdout 

;  BX  =  standard  output 

handle 

mov 

ah,40h 

;  function  40H  =  write 

file/device 

int 

21h 

;  transfer  to  MS-DOS 

ret 

;  back  to  caller 

pmsg 

endp 

-TEXT 

ends 

-DATA 

segment 

para  public  '1 

DATA ' 

static  &  variable  data  segment 

cname 

db 

'CHILD.EXE' , 0 

pathname  of  child  process 

pars 

dw 

-ENVIR 

segment  of  environment  block 

dd 

tail 

long  address,  command  tail 

dd 

fcbl 

long  address,  default  FCB  #1 

dd 

fcb2 

long  address,  default  FCB  #2 

tail 

db 

fcbl -tail-2 

command  tail  for  child 

db 

'dummy  command  tail',cr 

fcbl 

db 

0 

copied  into  default  FCB  #1  in 

db 

11  dup  ('  ') 

child's  program  segment  prefix 

db 

2  5  dup  ( 0 ) 

fcb2 

db 

0 

■  copied  into  default  FCB  #2  in 

db 

11  dup  (•  ') 

child's  program  segment  prefix 

db 

2  5  dup  ( 0 ) 

msgl 

db 

cr, If, ' Parent 

executing! ' 

'  f cr, If 

msgl— len  equ 

$-msg1 

msg2 

db 

cr, If, 'Memory 

resize  failed,  error  code=' 

msg2a 

db 

' xxh . ' , cr, If 

msg2— len  equ 

$-msg2 

msg3 

db 

cr, If, 'EXEC  call  failed. 

error  code=' 

msg3a 

db 

'xxh. ' , cr, If 

msg3— len  equ 

$-msg3 

msg4 

db 

cr, If, ' Parent 

regained  control!' 

db 

cr, If, ' Child 

termination 

ft 

0 

11 

msg4a 

db 

'xxh,  return 

code= ' 

msg4b 

db 

' xxh . ' , cr.  If 

msg4— len  equ 

$-msg4 

-DATA 

ends 

-ENVIR 

segment 

para  public  ' 

DATA ' 

;  example  environment  block 

;  to  be  passed  to  child 

Figure  10-3.  Continued.  (more) 
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db 

' PATH= '  ,  0 

;  basic  PATH,  PROMPT, 

db 

' PROMPT=$p$_$n$g' ,  0 

;  and  COMSPEC  strings 

db 

' COMSPEC=C : \ COMMAND . COM ' 

,0 

db 

0 

;  extra  null  terminates 

block 

-ENVIR 

ends 

-STACK 

segment 

para  stack  'STACK' 

db 

stksize  dup  (?) 

-STACK 

ends 

end 

main 

;  defines  program  entry 

point 

Figure  10-3.  Continued. 


name  child 

title  'CHILD  process' 

;  CHILD.EXE  -  a  simple  process  loaded  by  PARENT.EXE 

;  to  demonstrate  the  MS-DOS  EXEC  call.  Subfunction  OOH. 

;  Ray  Duncan,  June  1987 


stdin 

equ 

0 

stdout 

equ 

1 

stderr 

equ 

2 

cr 

equ 

Odh 

If 

equ 

Oah 

standard  input 
standard  output 
standard  error 

ASCII  carriage  return 
ASCII  linefeed 


DGROUP  group  -DATA, STACK 


—TEXT  segment  byte  public  'CODE'  ;  executable  code  segment 


assume  cs :—TEXT, ds :—DATA, ss : STACK 


main 

proc 

far 

mov 

ax, —DATA 

mov 

ds,  ax 

;  entry  point  from  MS-DOS 
;  set  DS  =  our  data  segment 


;  display  child  message  . . . 


Figure  10-4.  CHILD.  ASM,  source  code  for  CHILD.EXE. 
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mov 

dx, offset  msg 

;  DS:DX  =  address  of  message 

mov 

cx, msg— len 

;  CX  =  length  of  message 

mov 

bx, stdout 

;  BX  =  standard  output  handle 

mov 

ah,40h 

;  AH  =  fxn  40H,  write  file/device 

int 

21h 

;  transfer  to  MS-DOS 

jc 

main2 

;  jump  if  any  error 

mov 

ax, 4c00h 

;  no  error,  terminate  child 

int 

21h 

;  with  return  code  =  0 

main2 : 

mov 

ax, 4c01 h 

;  error,  terminate  child 

int 

21h 

;  with  return  code  =  1 

main 

endp 

;  end  of  main  procedure 

-TEXT 

ends 

-DATA 

segment 

para  public  ’DATA' 

;  static  &  variable  data  segment 

msg 

db 

cr, If, 'Child  executing! 

•,cr,lf 

msg— len 

equ 

$-msg 

-DATA 

ends 

STACK 

segment 

para  stack  'STACK' 

dw 

64  dup  (?) 

STACK 

ends 

end 

main 

;  defines  program  entry  point 

Figure  10-4.  Continued. 


PARENT.ASM  can  be  assembled  and  linked  into  the  executable  program  PARENT.EXE 
with  the  following  commands: 

OMASM  PARENT;  <Enter> 

OLINK  PARENT;  <Enter> 

Similarly,  CHILD.ASM  can  be  assembled  and  linked  into  the  file  CHILD.EXE  as  follows: 

OMASM  CHILD;  <Enter> 

OLINK  CHILD;  <Enter> 

When  PARENT.EXE  is  executed  with  the  command 

OPARENT  <Enter> 
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PARENT  reduces  the  size  of  its  main  memory  block  with  a  call  to  Interrupt  21H  Function 
4AH,  to  maximize  the  amount  of  free  memory  in  the  system,  and  then  calls  the  EXEC  func¬ 
tion  to  load  and  execute  CHILD.EXE. 

CHILD.EXE  runs  exactly  as  though  it  had  been  loaded  directly  by  COMMAND.COM. 
CHILD  resets  the  DS  segment  register  to  point  to  its  own  data  segment,  uses  Interrupt  21H 
Function  40H  to  display  a  message  on  standard  output,  and  then  terminates  using  Interrupt 
21H  Function  4CH,  passing  a  return  code  of  zero. 

When  PARENT.EXE  regains  control,  it  first  checks  the  carry  flag  to  determine  whether 
the  EXEC  call  succeeded.  If  the  EXEC  call  failed,  PARENT  displays  an  error  message  and 
terminates  with  Interrupt  21H  Function  4CH,  itself  passing  a  nonzero  return  code  to 
COMMAND.COM  to  indicate  an  error. 

Otherwise,  PARENT  uses  Interrupt  21H  Function  4DH  to  obtain  CHILD.EXE’s  termination 
type  and  return  code,  which  it  converts  to  ASCII  and  displays.  PARENT  then  terminates 
using  Interrupt  21H  Function  4CH  and  passes  a  return  code  of  zero  to  COMMAND.COM 
to  indicate  success.  COMMAND.COM  in  turn  receives  control  and  displays  a  new  user 
prompt. 


Using  EXEC  to  Load  Overlays 

Loading  overlays  with  the  EXEC  function  is  much  less  complex  than  using  EXEC  to  run 
another  program.  The  main  program,  called  the  root  segment,  must  carry  out  the  follow¬ 
ing  steps  to  load  and  execute  an  overlay: 

1 .  Make  a  memory  block  available  to  receive  the  overlay. 

2.  Set  up  the  overlay  parameter  block  to  be  passed  to  the  EXEC  function. 

3.  Call  the  EXEC  function  to  load  the  overlay. 

4.  Execute  the  code  within  the  overlay  by  transferring  to  it  with  a  far  call. 

The  overlay  itself  can  be  constructed  as  either  a  memory  image  (.COM)  or  a  relocatable 
(.EXE)  file  and  need  not  be  the  same  type  as  the  root  program.  In  either  case,  the  overlay 
should  be  designed  so  that  the  entry  point  (or  a  pointer  to  the  entry  point)  is  at  the  begin¬ 
ning  of  the  module  after  it  is  loaded.  This  allows  the  root  and  overlay  modules  to  be  main¬ 
tained  separately  and  avoids  a  need  for  the  root  to  have  “magical”  knowledge  of  addresses 
within  the  overlay. 

To  prevent  users  from  inadvertently  running  an  overlay  directly  from  the  command  line, 
overlay  files  should  be  assigned  an  extension  other  than  .COM  or  .EXE.  The  most  conve¬ 
nient  method  relates  overlays  to  their  root  segment  by  assigning  them  the  same  filename 
but  an  extension  such  as  .OVL  or  .OVl,  .OV2,  and  so  on. 

Making  memory  available 

If  EXEC  is  to  load  a  child  program  successfully,  the  parent  must  release  memory.  In 
contrast,  EXEC  loads  an  overlay  into  memory  that  belongs  to  the  calling  program.  If  the 
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root  segment  is  a  .COM  program  and  has  not  explicitly  released  extra  memory,  the  root 
segment  program  need  only  ensure  that  the  system  contains  enough  memory  to  load  the 
overlay  and  that  the  overlay  load  address  does  not  conflict  with  its  own  code,  data,  or 
stack  areas. 

If  the  root  segment  program  was  loaded  from  a  .EXE  file,  no  straightforward  way  exists 
for  it  to  determine  unequivocally  how  much  memory  it  already  owns.  The  simplest  course 
is  for  the  program  to  release  all  extra  memory,  as  discussed  earlier  in  the  section  on  load¬ 
ing  a  child  program,  and  then  use  the  MS-DOS  memory  allocation  function  (Interrupt  21H 
Function  48H)  to  obtain  a  new  block  of  memory  that  is  large  enough  to  hold  the  overlay. 

Preparing  overlay  parameters 

When  it  is  used  to  load  an  overlay,  the  EXEC  function  requires  two  major  parameters: 

•  The  address  of  the  pathname  for  the  overlay  file 

•  The  address  of  an  overlay  parameter  block 

As  for  a  child  program,  the  pathname  for  the  overlay  file  must  be  an  unambiguous  ASCII2 
file  specification  (again,  no  wildcard  characters),  and  it  must  include  an  explicit  extension. 
As  before,  if  a  path  and/or  drive  are  not  included  in  the  pathname,  the  current  directory 
and  default  drive  are  used. 

The  overlay  parameter  block  contains  the  segment  address  at  which  the  overlay  should  be 
loaded  and  a  fixup  value  to  be  applied  to  any  relocatable  items  within  the  overlay  file.  If 
the  overlay  file  is  in  .EXE  format,  the  fixup  value  is  typically  the  same  as  the  load  address;  if 
the  overlay  is  in  memory-image  (.COM)  format,  the  fixup  value  should  be  zero.  The  EXEC 
function  does  not  attempt  to  validate  the  load  address  or  the  fixup  value  or  to  ensure  that 
the  load  address  actually  belongs  to  the  calling  program. 

Loading  and  executing  the  overlay 

After  the  root  segment  program  has  prepared  the  filename  of  the  overlay  file  and  the 
overlay  parameter  block,  it  can  invoke  the  EXEC  function  to  load  the  overlay  by  issuing  an 
Interrupt  21H  with  the  registers  set  as  follows: 

AH  =  4BH 

AL  =  03H  (EXEC  subfunction  to  load  overlay) 

DS:DX  =  segment:offset  of  overlay  file  pathname 

ES:BX  =  segment:offset  of  overlay  parameter  block 

Upon  return  from  Interrupt  21H,  the  root  segment  must  test  the  carry  flag  to  determine 
whether  the  overlay  was  loaded.  If  the  carry  flag  is  clear,  the  overlay  file  was  located  and 
brought  into  memory  at  the  requested  address.  The  overlay  can  then  be  entered  by  a  far 
call  and  should  exit  back  to  the  root  segment  with  a  far  return. 

If  the  carry  flag  is  set,  the  overlay  file  was  not  found  or  some  other  (probably  severe)  sys¬ 
tem  problem  was  encountered,  and  the  AX  register  contains  an  error  code.  With  MS-DOS 
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versions  3.0  and  later,  Interrupt  21H  Function  59H  can  be  used  to  get  more  information 
about  the  EXEC  failure.  An  invalid  load  address  supplied  in  the  overlay  parameter  block 
does  not  (usually)  cause  the  EXEC  function  itself  to  fail  but  may  result  in  the  disconcerting 
message  Memory  Allocation  Error,  System  Halted  when  the  root  program  terminates. 

An  overlay  example 

The  source  programs  ROOT.ASM  in  Figure  10-5  and  OVERLAY. ASM  in  Figure  10-6  demon¬ 
strate  the  use  of  EXEC  to  load  a  program  overlay.  The  program  ROOT.EXE  is  executable 
from  the  MS-DOS  prompt;  it  represents  the  root  segment  of  an  application.  OVERLAY  is 
constructed  as  a  .EXE  file  (although  it  is  named  OVERLAY. OVL  because  it  cannot  be  run 
alone)  and  represents  a  subprogram  that  can  be  loaded  by  the  root  segment  when  and 
if  it  is  needed. 

name  root 

title  'ROOT -  demonstrate  EXEC  overlay' 

;  ROOT.EXE  -  demonstration  of  EXEC  for  overlays 

;  Uses  MS-DOS  EXEC  (Int  21 H  Function  4BH  Subfunction  03H) 

;  to  load  an  overlay  named  OVERLAY. OVL,  calls  a  routine 
;  within  the  OVERLAY,  then  recovers  control  and  terminates. 

;  Ray  Duncan,  June  1987 


stdin 

equ 

0 

/ 

standard  input 

stdout 

equ 

1 

/ 

standard  output 

stderr 

equ 

2 

standard  error 

stksize 

equ 

128 

size  of  stack 

cr 

equ 

Odh 

; 

ASCII  carriage  return 

If 

equ 

Oah 

ASCII  linefeed 

DGROUP 

group 

_D  AT  A, -STACK 

_TEXT 

segment 

byte  public  'CODE* 

executable  code  segment 

assume 

cs :_TEXT, ds :_DATA, ss : 

-STACK 

stk_seg 

dw 

7 

original  SS  contents 

stk_ptr 

dw 

7 

; 

original  SP  contents 

Figure  10-5.  ROOT.ASM,  source  code  for  ROOT.EXE. 


(more) 
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main  proc  far 

mov  ax, —DATA 

mov  ds,ax 

mov  ax,es 

mov  bx,ss 

sub  bx,ax 

add  bx, stksize/1 6 

mov  ah, 4 ah 

int  21h 

jc  maini 


mov  dx, offset  DGR0UP:msg1 
mov  cx,,msg1— len 

call  pmsg 

mov  bx,1000h 

mov  ah,48h 

int  21 h 

jc  main2 

mov  pars, ax 

mov  pars+2,ax 

mov  word  ptr  entry+2,ax 

push  ds 

mov  stk— seg,ss 

mov  stk— ptr, sp 

mov  ax,ds 

mov  es,ax 

mov  dx, offset  DGROUP:oname 

mov  bx, offset  DGROUPipars 

mov  ax,4b03h 

int  21 h 

cli 

mov  ss,stk— seg 

mov  sp, stk— ptr 

sti 

pop  ds 

jc  main3 


Figure  10-5.  Continued. 


entry  point  from  MS-DOS 
set  DS  =  our  data  segment 

now  give  back  extra  memory 
AX  =  segment  of  PSP  base 
BX  =  segment  of  stack  base 
reserve  seg  stack  -  seg  psp 
plus  paragraphs  of  stack 
fxn  4 AH  =  modify  memory  block 
transfer  to  MS-DOS 
jump  if  resize  failed 

display  message  'Root 
segment  executing...' 

DS:DX  =  address  of  message 
CX  =  length  of  message 

allocate  memory  for  overlay 
get  64  KB  (4096  paragraphs) 
fxn  48H,  allocate  mem  block 
transfer  to  MS-DOS 
jump  if  allocation  failed 

set  load  address  for  overlay 
set  relocation  segment  for  overlay 
set  segment  of  entry  point 

save  root's  data  segment 
save  root's  stack  pointer 


now  use  EXEC  to  load  overlay 
set  ES  =  DS 

DS:DX  =  overlay  pathname 
ES;BX  =  parameter  block 
function  4BH,  subfunction  03H 
transfer  to  MS-DOS 

(for  bug  in  some  early  8088s) 
restore  root's  stack  pointer 

(for  bug  in  some  early  8088s) 
restore  DS  =  our  data  segment 

jump  if  EXEC  failed 

otherwise  EXEC  succeeded. . . 

(more) 


338  The  MS-DOS  Encyclopedia 


Article  10:  The  MS-DOS  EXEC  Function 


push 

ds 

call 

dword  ptr  entry 

pop 

ds 

mov 

dx, offset  DGROUP:msg5 

mov 

cx,msg5_len 

call 

pmsg 

mov 

ax, 4c00h 

int 

21h 

maini : 

mov 

bx, offset  DGROUP:msg2a 

call 

b2hex 

mov 

dx, offset  DGROUP:msg2 

mov 

CX, msg2_len 

call 

pmsg 

jmp 

main4 

main2 : 

mov 

bx, offset  DGROUP:msg3a 

call 

b2hex 

mov 

dx, offset  DGROUP:msg3 

mov 

cx,msg3_len 

call 

pmsg 

jmp 

main4 

mainS : 

mov 

bx, offset  DGROUP:msg4a 

call 

b2hex 

mov 

dx, offset  DGROUP:msg4 

mov 

cx,msg4_len 

call 

pmsg 

main4 : 

mov 

ax, 4c01 h 

int 

21h 

main 

endp 

b2hex 

proc 

near 

push 

ax 

shr 

al,  1 

shr 

al,  1 

shr 

al,  1 

shr 

al,  1 

call 

ascii 

mov 

[bx] ,al 

pop 

ax 

Figure  10-5.  Continued, 


;  save  our  data  segment 
;  now  call  the  overlay 
;  restore  our  data  segment 

;  display  message  that  root 
;  segment  regained  control... 
;  DS:DX  =  address  of  message 
;  CX  =  length  of  message 
;  display  it 

;  no  error,  terminate  program 
;  with  return  code  =  0 

;  convert  error  code 

;  display  message  'Memory 
;  resize  failed.  .  . ' 


;  convert  error  code 

;  display  message  'Memory 
;  allocation  failed. . . ' 


;  convert  error  code 

/display  message  'EXEC 
;  call  failed. . . ' 


;  error,  terminate  program 
;  with  return  code  =  1 

;  end  of  main  procedure 

;  convert  byte  to  hex  ASCII 
;  call  with  AL  =  binary  value 
;  BX  =  addr  to  store  string 


;  become  first  ASCII  character 
;  store  it 

(more) 
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and 

al,0fh 

;  isolate  lower  4  bits,  which 

call 

ascii 

;  become  the  second  ASCII  character 

mov 

[bx+1 ] , al 

;  store  it 

ret 

b2hex 

endp 

ascii 

proc 

near 

;  convert  value  OO-OFH  in  AL 

add 

al, 'O' 

;  into  a  "hex  ASCII"  character 

cmp 

al,'9' 

jle 

ascii2 

;  jump  if  in  range  00-09H, 

add 

al, 'A'-'9'-1 

;  offset  it  to  range  OA-OFH, 

ascii2 : 

ret 

;  return  ASCII  char,  in  AL. 

ascii 

endp 

pmsg 

proc 

near 

;  displays  message  on  standard  output 
;  call  with  DS:DX  =  address. 

;  CX  =  length 

mov 

bx, stdout 

;  BX  =  standard  output  handle 

mov 

ah, 40h 

;  function  40H  =  write  file/device 

int 

21h 

;  transfer  to  MS-DOS 

ret 

;  back  to  caller 

pmsg 

endp 

-TEXT 

ends 

-DATA 

segment 

para  public  'DATA' 

;  static  &  variable  data  segment 

oname 

db 

' OVERLAY . OVL  * , 0 

;  pathname  of  overlay  file 

pars 

dw 

0 

;  load  address  (segment)  for  file 

dw 

0 

;  relocation  (segment)  for  file 

entry 

dd 

0 

;  entry  point  for  overlay 

msgl 

db 

cr, If, 'Root  segment 

executing! ' , cr, If 

msgl— len  equ 

$-msg1 

msg2 

db 

cr, If , 'Memory  resize  failed,  error  code=' 

msg2a 

db 

' xxh . ' , cr.  If 

msg2— len  equ 

$-msg2 

msg3 

db 

cr, If , 'Memory  allocation  failed,  error  code=' 

msg3a 

db 

' xxh . ' , cr, If 

msg3_len  equ  $-msg3 
Figure  10-5.  Continued. 


(more) 
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msg4  db 
msg4a  db 
msg4_len  equ 


cr, If, 'EXEC  call  failed,  error  code=' 

' xxh. ' , cr, If 

$-msg4 


msgS  db  cr, If, 'Root  segment  regained  control !', cr.  If 

msg5_len  equ  $-msg5 


_DATA  ends 


—STACK  segment  para  stack  'STACK' 
db  stksize  dup  (?) 

-STACK  ends 


end  main 

Figure  10-5.  Continued. 


;  defines  program  entry  point 


name  overlay 

title  'OVERLAY  segment' 

;  OVERLAY. OVL  -  a  simple  overlay  segment 

;  loaded  by  ROOT.EXE  to  demonstrate  use  of 
;  the  MS-DOS  EXEC  call  Subfunction  03H. 

;  The  overlay  does  not  contain  a  STACK  segment 
;  because  it  uses  the  ROOT  segment's  stack. 

;  Ray  Duncan,  June  1987 


stdin 

equ 

0 

;  standard  input 

stdout 

equ 

1 

;  standard  output 

stderr 

equ 

2 

;  standard  error 

cr 

equ 

Odh 

;  ASCII  carriage  return 

If 

equ 

Oah 

;  ASCII  linefeed 

-TEXT 

segment 

byte  public  'CODE' 

;  executable  code  segment 

assume 

cs :-TEXT, ds :_DATA 

ovlay 

proc 

far 

;  entry  point  from  root  segment 

mov 

ax, -DATA 

;  set  DS  =  local  data  segment 

mov 

ds,  ax 

Figure  10-6.  OVERLAY.  ASM,  source  code  for  OVERLAYOVL. 


(more) 
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display  overlay  message 


mov 

dx, offset  msg  ; 

DS:DX  =  address  of  message 

mov 

cx, msg— len  ; 

cx  =  length  of  message 

mov 

bx,stdout  ; 

BX  =  standard  output  handle 

mov 

ah, 4 Oh  ; 

AH  =  fxn  40H,  write  file/device 

int 

21  h 

transfer  to  MS-DOS 

ret 

return  to  root  segment 

ovlay 

endp 

'* 

end  of  ovlay  procedure 

-TEXT 

ends 

-DATA 

segment 

para  public  'DATA*  ; 

static  &  variable  data  segment 

msg 

db 

cr, If , 'Overlay  executing! 

’,cr,lf 

msg— len 

equ 

$-msg 

-DATA 

ends 

end 

Figure  10-6.  Continued. 


ROOT.ASM  can  be  assembled  and  linked  into  the  executable  program  ROOT.EXE  with  the 
following  commands: 

C>^SM  ROOT;  <Enter> 

OlinK  ROOT;  <Enter> 

OVERLAY.ASM  can  be  assembled  and  linked  into  the  file  OVERLAY.  OVL  by  typing 

C>MASM  OVERLAY;  <Enter> 

C>LINK  OVERLAY, OVERLAY. OVL;  <Enter> 

The  Microsoft  Object  Linker  will  display  the  message 

Warning:  no  stack  segment 

but  this  message  can  be  ignored. 

When  ROOT.EXE  is  executed  with  the  command 

C>ROOT  <Enter> 

it  first  shrinks  its  main  memory  block  with  a  call  to  Interrupt  21H  Function  4AH  and  then 
allocates  a  separate  block  for  the  overlay  with  Interrupt  21H  Function  48H.  Next,  ROOT 
calls  the  EXEC  function  to  load  the  file  OVERLAY.  OVL  into  the  newly  allocated  memory 
block.  If  the  EXEC  function  fails,  ROOT  displays  an  error  message  and  terminates  with 
Interrupt  21H  Function  4CH,  passing  a  nonzero  return  code  to  COMMAND.COM  to  indi¬ 
cate  an  error.  If  the  EXEC  function  succeeds,  ROOT  saves  the  contents  of  its  DS  segment 
register  and  then  enters  the  overlay  through  an  indirect  far  call. 
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The  overlay  resets  the  DS  segment  register  to  point  to  its  own  data  segment,  displays  a 
message  using  Interrupt  21H  Function  40H,  and  then  returns.  Note  that  the  main  pro¬ 
cedure  of  the  overlay  is  declared  with  the  far  attribute  to  force  the  assembler  to  generate 
the  opcode  for  a  far  return. 

When  ROOT  regains  control,  it  restores  the  DS  segment  register  to  point  to  its  own  data 
segment  again  and  displays  an  additional  message,  also  using  Interrupt  21H  Function  40H, 
to  indicate  that  the  overlay  executed  successfully.  ROOT  then  terminates  using  Interrupt 
21H  Function  4CH,  passing  a  return  code  of  zero  to  indicate  success,  and  control  returns 
to  COMMAND.COM. 


Ray  Duncan 
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Article  11 

Terminate-and-Stay-Resident  Utilities 


The  MS-DOS  Terminate  and  Stay  Resident  system  calls  (Interrupt  21H  Function  31H  and 
Interrupt  27H)  allow  the  programmer  to  install  executable  code  or  program  data  in  a 
reserved  block  of  RAM,  where  it  resides  while  other  programs  execute.  Global  data,  inter¬ 
rupt  handlers,  and  entire  applications  can  be  made  RAM-resident  in  this  way.  Programs 
that  use  the  MS-DOS  terminate-and-stay-resident  capability  are  commonly  known  as 
TSR  programs  or  TSRs. 

This  article  describes  how  to  install  a  TSR  in  RAM,  how  to  communicate  with  the  resident 
program,  and  how  the  resident  program  can  interact  with  MS-DOS.  The  discussion  pro¬ 
ceeds  from  a  general  description  of  the  MS-DOS  functions  useful  to  TSR  programmers  to 
specific  details  about  certain  MS-DOS  structural  elements  necessary  to  proper  functioning 
of  a  TSR  utility  and  concludes  with  two  programming  examples. 

Note:  Microsoft  cannot  guarantee  that  the  information  in  this  article  will  be  valid  for  fu¬ 
ture  versions  of  MS-DOS. 


structure  of  a  Terminate-and-Stay-Resident  Utility 

The  executable  code  and  data  in  TSRs  can  be  separated  into  RAM-resident  and  transient 
portions  (Figure  11-1).  The  RAM-resident  portion  of  a  TSR  contains  executable  code  and 
data  for  an  application  that  performs  some  useful  function  on  demand.  The  transient  por¬ 
tion  installs  the  TSR;  that  is,  it  initializes  data  and  interrupt  handlers  contained  in  the  RAM- 
resident  portion  of  the  program  and  executes  an  MS-DOS  Terminate  and  Stay  Resident 
function  call  that  leaves  the  RAM-resident  portion  in  memory  and  frees  the  memory  used 
by  the  transient  portion.  The  code  in  the  transient  portion  of  a  TSR  runs  when  the  .EXE  or 
.COM  file  containing  the  program  is  executed;  the  code  in  the  RAM-resident  portion  runs 
only  when  it  is  explicitly  invoked  by  a  foreground  program  or  by  execution  of  a  hardware 
or  software  interrupt. 

TSRs  can  be  broadly  classified  as  passive  or  active,  depending  on  the  method  by  which 
control  is  transferred  to  the  RAM-resident  program.  A  passive  TSR  executes  only  when 
another  program  explicitly  transfers  control  to  it,  either  through  a  software  interrupt  or  by 
means  of  a  long  JMP  or  CALL.  The  calling  program  is  not  interrupted  by  the  TSR,  so  the 
status  of  MS-DOS,  the  system  BIOS,  and  the  hardware  is  well  defined  when  the  TSR  pro¬ 
gram  starts  to  execute. 

In  contrast,  an  active  TSR  is  invoked  by  the  occurrence  of  some  event  external  to  the 
currently  running  (foreground)  program,  such  as  a  sequence  of  user  keystrokes  or  a  pre¬ 
defined  hardware  interrupt.  Therefore,  when  it  is  invoked,  an  active  TSR  almost  always 
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Higher  addresses 


Lower  addresses 


Initialization  code  and  data 


Application  code  and  data 


Monitor  routines 


Program  segment  prefix 


Transient  portion 
(executed  when  .EXE  file  runs) 


>  RAM-resident  portion 


Figure  11-1.  Organization  of  a  TSR  program  in  memory. 


interrupts  some  other  program  and  suspends  its  execution.  To  avoid  disrupting  the  inter¬ 
rupted  program,  an  active  TSR  must  monitor  the  status  of  MS-DOS,  the  ROM  BIOS,  and 
the  hardware  and  take  control  of  the  system  only  when  it  is  safe  to  do  so. 

Passive  TSRs  are  generally  simpler  in  their  construction  than  active  TSRs  because  a  passive 
TSR  runs  in  the  context  of  the  calling  program;  that  is,  when  the  TSR  executes,  it  assumes 
that  it  can  use  the  calling  program’s  program  segment  prefix  (PSP),  open  files,  current 
directory,  and  so  on.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Program¬ 
ming  FOR  MS-DOS:  Structure  of  an  Application  Program.  It  is  the  calling  program’s  respon¬ 
sibility  to  ensure  that  the  hardware  and  MS-DOS  are  in  a  stable  state  before  it  transfers 
control  to  a  passive  TSR. 

An  active  TSR,  on  the  other  hand,  is  invoked  asynchronously;  that  is,  the  status  of  the 
hardware,  MS-DOS,  and  the  executing  foreground  program  is  indeterminate  when  the 
event  that  invokes  the  TSR  occurs.  Therefore,  active  TSRs  require  more  complex  code.  The 
RAM-resident  portion  of  an  active  TSR  must  contain  modules  that  monitor  the  operating 
system  to  determine  when  control  can  safely  be  transferred  to  the  application  portion  of 
the  TSR.  The  monitor  routines  typically  test  the  status  of  keyboard  input,  ROM  BIOS  inter¬ 
rupt  processing,  hardware  interrupt  processing,  and  MS-DOS  function  processing.  The 
TSR  activates  the  application  (the  part  of  the  RAM-resident  portion  that  performs  the  TSR’s 
main  task)  only  when  it  detects  the  appropriate  keyboard  input  and  determines  that  the 
application  will  not  interfere  with  interrupt  and  MS-DOS  function  processing. 

Keyboard  input 

An  active  TSR  usually  contains  a  RAM-resident  module  that  examines  keyboard  input 
for  a  predetermined  keystroke  sequence  called  a  “hot-key”  sequence.  A  user  executes  the 
RAM-resident  application  by  entering  this  hot-key  sequence  at  the  keyboard. 

The  technique  used  in  the  TSR  to  monitor  keyboard  input  depends  on  the  keyboard 
hardware  implementation.  On  computers  in  the  IBM  PC  and  PS/2  families,  the  keyboard 
coprocessor  generates  an  Interrupt  09H  for  each  keypress.  Therefore,  a  TSR  can  monitor 
user  keystrokes  by  installing  an  interrupt  handler  (interrupt  service  routine,  or  ISR)  for 
Interrupt  09H.  This  handler  can  thus  detect  a  specified  hot-key  sequence. 
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ROM  BIOS  interrupt  processing 

The  ROM  BIOS  routines  in  IBM  PCs  and  PS/2s  are  not  reentrant.  An  active  TSR  that  calls 
the  ROM  BIOS  must  ensure  that  its  code  does  not  attempt  to  execute  a  ROM  BIOS  function 
that  was  already  being  executed  by  the  foreground  process  when  the  TSR  program  took 
control  of  the  system. 

The  IBM  ROM  BIOS  routines  are  invoked  through  software  interrupts,  so  an  active  TSR 
can  monitor  the  status  of  the  ROM  BIOS  by  replacing  the  default  interrupt  handlers  with 
custom  interrupt  handlers  that  intercept  the  appropriate  BIOS  interrupts.  Each  of  these  in¬ 
terrupt  handlers  can  maintain  a  status  flag,  which  it  increments  before  transferring  control 
to  the  corresponding  ROM  BIOS  routine  and  decrements  when  the  ROM  BIOS  routine  has 
finished  executing.  Thus,  the  TSR  monitor  routines  can  test  these  flags  to  determine  when 
non-reentrant  BIOS  routines  are  executing. 

Hardware  interrupt  processing 

The  monitor  routines  of  an  active  TSR,  which  may  themselves  be  executed  as  the  result  of 
a  hardware  interrupt,  should  not  activate  the  application  portion  of  the  TSR  if  any  other 
hardware  interrupt  is  being  processed.  On  IBM  PCs,  for  example,  hardware  interrupts  are 
processed  in  a  prioritized  sequence  determined  by  an  Intel  8259A  Programmable  Inter¬ 
rupt  Controller.  The  8259A  does  not  allow  a  hardware  interrupt  to  execute  if  a  previous 
interrupt  with  the  same  or  higher  priority  is  being  serviced.  All  hardware  interrupt 
handlers  include  code  that  signals  the  8259A  when  interrupt  processing  is  completed. 

(The  programming  interface  to  the  8259A  is  described  in  IBM’s  Technical  Reference 
manuals  and  in  Intel’s  technical  literature.) 

If  a  TSR  were  to  interrupt  the  execution  of  another  hardware  interrupt  handler  before  the 
handler  signaled  the  8259A  that  it  had  completed  its  interrupt  servicing,  subsequent  hard¬ 
ware  interrupts  could  be  inhibited  indefinitely.  Inhibition  of  high-priority  hardware  inter¬ 
rupts  such  as  the  timer  tick  (Interrupt  08H)  or  keyboard  interrupt  (Interrupt  09H)  could 
cause  a  system  crash.  For  this  reason,  an  active  TSR  must  monitor  the  status  of  all  hardware 
interrupt  processing  by  interrogating  the  8259A  to  ensure  that  control  is  transferred  to  the 
RAM-resident  application  only  when  no  other  hardware  interrupts  are  being  serviced. 

MS-DOS  function  processing 

Unlike  the  IBM  ROM  BIOS  routines,  MS-DOS  is  reentrant  to  a  limited  extent.  That  is,  there 
are  certain  times  when  MS-DOS’s  servicing  of  an  Interrupt  21H  function  call  invoked  by  a 
foreground  process  can  be  suspended  so  that  the  RAM-resident  application  can  make  an 
Interrupt  21H  function  call  of  its  own.  For  this  reason,  an  active  TSR  must  monitor  operat¬ 
ing  system  activity  to  determine  when  it  is  safe  for  the  TSR  application  to  make  its  calls 
to  MS-DOS. 
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MS-DOS  Support  for  Terminate-and-Stay-Resident 
Programs 

Several  MS-DOS  system  calls  are  useful  for  supporting  terminate-and-stay-resident 
utilities.  These  are  listed  in  Table  11-1.  See  SYSTEM  CALLS. 

Table  11-1.  MS-DOS  Functions  Useful  in  TSR  Programs. 


Function  Name  Call  With 


Returns 


Comment 


Terminate  and 
Stay  Resident 


Terminate  and 
Stay  Resident 


Set  Interrupt 
Vector 


Get  Interrupt 
Vector 


Set  PSP  Address 


Get  PSP  Address 


Set  Extended 
Error  Information 


AH  =  31H 
AL  =  return  code 
DX  =  size  of  resident  program 
(in  l6-byte  paragraphs) 
INT21H 

CS  =  PSP 

DX  =  size  of  resident  program 
(bytes) 

INT27H 

AH  =  25H 

AL  =  interrupt  number 
DS:DX  =  address  of  interrupt 
handler 
INT21H 

AH  =  35H 

AL  =  interrupt  number 
INT21H 


Nothing  Preferred  over  Interrupt 

27H  with  MS-DOS 
versions  2.x  and  later 


Nothing  Provided  for  com¬ 

patibility  with 
MS-DOS  versions  1.x 


Nothing 


ES:BX  =  address  of 
interrupt  handler 


AH  =  50H  Nothing 

BX  =  PSP  segment 

INT21H 


AH  =  51H  BX  =  PSP  segment 

INT21H 

AX=5D0AH  Nothing  MS-DOS  versions  3.1 

DS:DX  =  address  of  1 1-word  data  structure:  and  later 

word  0:  register  AX 

as  returned  by  Function  59H 
word  1:  register  BX 
word  2:  register  CX 
word  3:  register  DX 
word  4:  register  SI 
word  5:  register  DI 
word  6:  register  DS 
word  7:  register  ES 
words  8-OAH:  reserved;  should  be  0 

INT21H 


(more) 
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Function  Name 

CaUWlth 

Returns 

Get  Extended 

AH  =  59H 

AX  =  extended  error 

Error  Information 

BX  =  0 

code 

INT21H 

BH  =  error  class 

BL  =  suggested  action 

CH  =  error  locus 

Set  Disk 

AH=1AH 

Nothing 

Transfer  Area 

DS:DX=  address  of  DTA 

Address 

INT21H 

Get  Disk 

AH  =  2FH 

ES:BX  *  address  of 

Transfer  Area 

INT21H 

current  DTA 

Address 

Get  InDOS  Flag 

AH  =  34H 

ES:BX  =  address  of 

Address 

INT21H 

InDOS  flag 

Terminate-and-stay-resident  functions 

MS-DOS  provides  two  mechanisms  for  terminating  the  execution  of  a  program  while  leav¬ 
ing  a  portion  of  it  resident  in  RAM.  The  preferred  method  is  to  execute  Interrupt  21H  Func¬ 
tion  31H. 

Interrupt  21H  Function  31H 

When  this  Interrupt  21H  function  is  called,  the  value  in  DX  specifies  the  amount  of  RAM 
(in  paragraphs)  that  is  to  remain  allocated  after  the  program  terminates,  starting  at  the 
program  segment  prefix  (PSP).  The  function  is  similar  to  Function  4CH  (Terminate 
Process  with  Return  Code)  in  that  it  passes  a  return  code  in  AL,  but  it  differs  in  that  open 
files  are  not  automatically  closed  by  Function  31H. 

Interrupt  27H 

When  Interrupt  27H  is  executed,  the  value  passed  in  DX  specifies  the  number  of  bytes  of 
memory  required  for  the  RAM-resident  program.  MS-DOS  converts  the  value  passed  in  DX 
from  bytes  to  paragraphs,  sets  AL  to  zero,  and  jumps  to  the  same  code  that  would  be  exe¬ 
cuted  for  Interrupt  21H  Function  31H,  Interrupt  27H  is  less  flexible  than  Interrupt  21H 
Function  31H  because  it  limits  the  size  of  the  program  that  can  remain  resident  in  RAM  to 
64  KB,  it  requires  that  CS  point  to  the  base  of  the  PSP,  and  it  does  not  pass  a  return  code. 
Later  versions  of  MS-DOS  support  Interrupt  27H  primarily  for  compatibility  with  versions 
1.x. 

TSR  RAM  management 

In  addition  to  the  RAM  explicitly  allocated  to  the  TSR  by  means  of  the  value  in  DX,  the 
RAM  allocated  to  the  TSR’s  environment  remains  resident  when  the  installation  portion 
of  the  TSR  program  terminates.  (The  paragraph  address  of  the  environment  is  found  at 
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offset  2CH  in  the  TSR’s  PSP.)  Moreover,  if  the  installation  portion  of  a  TSR  program  has 
used  Interrupt  21H  Function  48H  (Allocate  Memory  Block)  to  allocate  additional  RAM,  this 
memory  also  remains  allocated  when  the  program  terminates.  If  the  RAM-resident  pro¬ 
gram  does  not  need  this  additional  RAM,  the  installation  portion  of  the  TSR  program 
should  free  it  explicitly  by  using  Interrupt  21H  Function  49H  (Free  Memory  Block)  before 
executing  Interrupt  21H  Function  31H. 

Set  and  Get  Interrupt  Vector  functions 

Two  Interrupt  21H  function  calls  are  available  to  inspect  or  update  the  contents  of  a 
specified  8086-family  interrupt  vector.  Function  25H  (Set  Interrupt  Vector)  updates  the 
vector  of  the  interrupt  number  specified  in  the  AL  register  with  the  segment  and  offset 
values  specified  in  DS:DX.  Function  35H  (Get  Interrupt  Vector)  performs  the  inverse 
operation:  It  copies  the  current  vector  of  the  interrupt  number  specified  in  AL  into  the 
ES:BX  register  pair. 

Although  it  is  possible  to  manipulate  interrupt  vectors  directly,  the  use  of  Interrupt  21H 
Functions  25H  and  35H  is  generally  more  convenient  and  allows  for  upward  compatibility 
with  future  versions  of  MS-DOS. 

Set  and  Get  PSP  Address  functions 

MS-DOS  uses  a  program’s  PSP  to  keep  track  of  certain  data  unique  to  the  program,  includ¬ 
ing  command-line  parameters  and  the  segment  address  of  the  program’s  environment.  See 
PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Structure 
of  an  Application  Program.  To  access  this  information,  MS-DOS  maintains  an  internal  vari¬ 
able  that  always  contains  the  location  of  the  PSP  associated  with  the  foreground  process. 
When  a  RAM-resident  application  is  activated,  it  should  use  Interrupt  21H  Functions  50H 
(Set  Program  Segment  Prefix  Address)  and  51H  (Get  Program  Segment  Prefix  Address)  to 
preserve  the  current  contents  of  this  variable  and  to  update  the  variable  with  the  location 
of  its  own  PSP.  Function  50H  (Set  Program  Segment  Prefix  Address)  updates  an  internal 
MS-DOS  variable  that  locates  the  PSP  currently  in  use  by  the  foreground  process.  Function 
51H  (Get  Program  Segment  Prefix  Address)  returns  the  contents  of  the  internal  MS-DOS 
variable  to  the  caller. 

Set  and  Get  Extended  Error  Information  functions 

In  MS-DOS  versions  3.1  and  later,  the  RAM-resident  program  should  preserve  the  fore¬ 
ground  process’s  extended  error  information  so  that,  if  the  RAM-resident  application 
encounters  an  MS-DOS  error,  the  extended  error  information  pertaining  to  the  foreground 
process  will  still  be  available  and  can  be  restored.  Interrupt  21H  Functions  59H  and 
5D0AH  provide  a  mechanism  for  the  RAM-resident  program  to  save  and  restore  this 
information  during  execution  of  a  TSR  application. 

Function  59H  (Get  Extended  Error  Information),  which  became  available  in  version  3.0, 
returns  detailed  information  on  the  most  recently  detected  MS-DOS  error.  The  inverse 
operation  is  performed  by  Function  5D0AH  (Set  Extended  Error  Information),  which  can 
be  used  only  in  MS-DOS  versions  3.1  and  later.  This  function  copies  extended  error 
information  to  MS-DOS  from  a  data  structure  defined  in  the  calling  program. 
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Set  and  Get  Disk  Transfer  Area  Address  functions 

Several  MS-DOS  data  transfer  functions,  notably  Interrupt  21H  Functions  21H,  22H,  27H, 
and  28H  (the  Random  Read  and  Write  functions)  and  Interrupt  21H  Functions  14H  and  15H 
(the  Sequential  Read  and  Write  functions),  require  a  program  to  specify  a  disk  transfer  area 
(DTA).  By  default,  a  program’s  DTA  is  located  at  offset  80H  in  its  program  segment  prefix. 
If  a  RAM-resident  application  calls  an  MS-DOS  function  that  uses  a  DTA,  the  TSR  should 
save  the  DTA  address  belonging  to  the  interrupted  program  by  using  Interrupt  21H  Func¬ 
tion  2FH  (Get  Disk  Transfer  Area  Address),  supply  its  own  DTA  address  to  MS-DOS  using 
Interrupt  21H  Function  lAH  (Set  Disk  Transfer  Area  Address),  and  then,  before  terminat¬ 
ing,  restore  the  interrupted  program’s  DTA. 

The  MS-DOS  idle  Interrupt  (Interrupt  28H) 

Several  of  the  first  12  MS-DOS  functions  (OlH  through  OCH)  must  wait  for  the  occurrence 
of  an  expected  event  such  as  a  user  keypress.  These  functions  contain  an  “idle  loop”  in 
which  looping  continues  until  the  event  occurs.  To  provide  a  mechanism  for  other  system 
activity  to  take  place  while  the  idle  loop  is  executing,  these  MS-DOS  functions  execute  an 
Interrupt  28H  from  within  the  loop. 

The  default  MS-DOS  handler  for  Interrupt  28H  is  only  an  IRET  instruction.  By  supplying 
its  own  handler  for  Interrupt  28H,  a  TSR  can  perform  some  useful  action  at  times  when 
MS-DOS  is  otherwise  idle.  Specifically,  a  custom  Interrupt  28H  handler  can  be  used  to 
examine  the  current  status  of  the  system  to  determine  whether  or  not  it  is  safe  to  activate 
the  RAM-resident  application. 


Determining  MS-DOS  Status 

A  TSR  can  infer  the  current  status  of  MS-DOS  from  knowledge  of  its  internal  use  of  stacks 
and  from  a  pair  of  internal  status  flags.  This  status  information  is  essential  to  the  proper 
execution  of  an  active  TSR  because  a  RAM-resident  application  can  make  calls  to  MS-DOS 
only  when  those  calls  will  not  disrupt  an  earlier  call  made  by  the  foreground  process. 

MS-DOS  internal  stacks 

MS-DOS  versions  2.0  and  later  may  use  any  of  three  internal  stacks:  the  I/O  stack 
(JOStacli),  the  disk  stack  iDiskStacH),  and  the  auxiliary  stack  iAuxStack).  In  general, 
lOStack  is  used  for  Interrupt  21H  Functions  OlH  through  OCH  and  DiskStack  is  used  for 
the  remaining  Interrupt  21H  functions;  AuxStack  is  normally  used  only  when  MS-DOS  has 
detected  a  critical  error  and  subsequently  executed  an  Interrupt  24H.  See  PROGRAMMING 
IN  THE  MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Exception  Handlers.  Specifically, 
MS-DOS’s  internal  stack  use  depends  on  which  MS-DOS  function  is  being  executed  and 
on  the  value  of  the  critical  error  flag. 

The  critical  error  flag 

The  critical  error  flag  {ErrorMod^  is  a  1-byte  flag  that  MS-DOS  uses  to  indicate  whether 
or  not  a  critical  error  has  occurred.  During  normal,  errorless  execution,  the  value  of  the 
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critical  error  flag  is  zero.  Whenever  MS-DOS  detects  a  critical  error,  it  sets  this  flag  to  a 
nonzero  value  before  it  executes  Interrupt  24H.  If  an  Interrupt  24H  handler  subsequently 
invokes  an  MS-DOS  function  by  using  Interrupt  21H,  the  nonzero  value  of  the  critical  error 
flag  tells  MS-DOS  to  use  its  auxiliary  stack  for  Interrupt  21H  Functions  OlH  through  OCH 
instead  of  using  the  I/O  stack  as  it  normally  would. 

In  other  words,  when  control  is  transferred  to  MS-DOS  through  Interrupt  21H,  the  function 
number  and  the  critical  error  flag  together  determine  MS-DOS  stack  use  for  the  function. 
Figure  11-2  outlines  the  internal  logic  used  on  entry  to  an  MS-DOS  function  to  select  which 
stack  is  to  be  used  during  processing  of  the  function.  As  stated  above,  for  Functions  OlH 
through  OCH,  MS-DOS  uses  lOStack  if  the  critical  error  flag  is  zero  and  AwcStack  if  the 
flag  is  nonzero.  For  function  numbers  greater  than  OCH,  MS-DOS  usually  uses  DiskStack, 
but  Functions  50H,  51H,  and  59H  are  important  exceptions.  Functions  50H  and  51H  use 
either  lOStack  (in  versions  2.x)  or  the  stack  supplied  by  the  calling  program  (in  versions 
3.x).  In  version  3.0,  Function  59H  uses  either  lOStack  or  Ai4xStack,  depending  on  the 
value  of  the  critical  error  flag,  but  in  versions  3.1  and  later.  Function  59H  always  uses 
AwcStack 

MS-DOS  versions  2.x 

if  (FunctionNumber  >=  OlH  and  FunctionNumber  <=  OCH) 
or 

FunctionNumber  =  50H 
or 

FunctionNumber  =  51H 

then  if  ErrorMode  =  0 
then  use  lOStack 
else  use  AuxStack 

else  ErrorMode  =  0 
use  DiskStack 

MS-DOS  version  3.0 

if  FunctionNumber  =  50H 
or 

FunctionNumber  =  51 H 
or 

FunctionNumber  =  62H 
then  use  caller's  stack 

else  if  (FunctionNumber  >=  OlH  and  FunctionNumber  <=  OCH) 
or 

Function  Number  =  59H 

then  if  ErrorMode  =  0 
then  use  lOStack 
else  use  AuxStack 

else  ErrorMode  =  0 
use  DiskStack 

Figure  11-2.  Strategy for  use  of  MS-DOS  internal  stacks.  ( more) 
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MS-DOS  versions  3*1  and  later 

if  FunctionNumber  =  33H 
or 

FunctionNumber  =  50H 
or 

FunctionNumber  =  51H 
or 

FunctionNumber  =  62H 
then  use  caller's  stack 

else  if  (FunctionNumber  >=  01 H  and  FunctionNumber  <=  OCH) 

then  if  ErrorMode  =  0 
then  use  lOStack 
else  use  AuxStack 

else  if  FunctionNumber  =  59H 
then  use  AuxStack 
else  ErrorMode  =  0 
use  DiskStack 

Figure  11~2.  Continued. 

This  scheme  makes  Functions  OlH  through  OCH  reentrant  in  a  limited  sense,  in  that  a 
substitute  critical  error  (Interrupt  24H)  handler  invoked  while  the  critical  error  flag 
is  nonzero  can  still  use  these  Interrupt  21H  functions.  In  this  situation,  because  the 
flag  is  nonzero,  AvtxStack  is  used  for  Functions  OlH  through  OCH  instead  of  lOStack 
Thus,  if  lOStack  is  in  use  when  the  critical  error  is  detected,  its  contents  are  preserved 
during  the  handler’s  subsequent  calls  to  these  functions. 

The  stack-selection  logic  differs  slightly  between  MS-DOS  versions  2  and  3.  In  versions 
3.x,  a  few  functions — notably  50H  and  51H — avoid  using  any  of  the  MS-DOS  stacks. 
These  functions  perform  uncomplicated  tasks  that  make  minimal  demands  for  stack 
space,  so  the  calling  program’s  stack  is  assumed  to  be  adequate  for  them. 

The  InDOS  flag 

InDOS  is  a  1-byte  flag  that  is  incremented  each  time  an  Interrupt  21H  function  is  invoked 
and  decremented  when  the  function  terminates.  The  flag’s  value  remains  nonzero  as  long 
as  code  within  MS-DOS  is  being  executed.  The  value  of  InDOS  does  not  indicate  which 
internal  stack  MS-DOS  is  using. 

Whenever  MS-DOS  detects  a  critical  error,  it  zeros  InDOS  before  it  executes  Interrupt  24H. 
This  action  is  taken  to  accommodate  substitute  Interrupt  24H  handlers  that  do  not  return 
control  to  MS-DOS.  If  InDOS  were  not  zeroed  before  such  a  handler  gained  control,  its 
value  would  never  be  decremented  and  would  therefore  be  incorrect  during  subsequent 
calls  to  MS-DOS. 

The  address  of  the  1-byte  InDOS  flag  can  be  obtained  from  MS-DOS  by  using  Interrupt 
21H  Function  34H  (Return  Address  of  InDOS  Flag).  In  versions  3.1  and  later,  the  1-byte  crit¬ 
ical  error  flag  is  located  in  the  byte  preceding  InDOS,  so,  in  effect,  the  address  of  both 
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flags  can  be  found  using  Function  34H.  Unfortunately,  there  is  no  easy  way  to  find  the 
critical  error  flag  in  other  versions.  The  recommended  technique  is  to  scan  the  MS-DOS 
segment,  which  is  returned  in  the  ES  register  by  Function  34H,  for  one  of  the  following 
sequences  of  instructions: 


test 

ss : [CriticalErrorFlag] , OFFH 

/(versions  3.1  and  later) 

jne 

NearLabel 

push 

ss : [NearWord] 

int 

28H 

or 


cmp 

ss : [CriticalErrorFlag] , 00 

; (versions  earlier  than  3 

jne 

NearLabel 

int 

28H 

When  the  TEST  or  CMP  instruction  has  been  identified,  the  offset  of  the  critical  error  flag 
can  be  obtained  from  the  instruction’s  operand  field. 


The  Multiplex  Interrupt 

The  MS-DOS  multiplex  interrupt  (Interrupt  2FH)  provides  a  general  mechanism  for  a 
program  to  verify  the  presence  of  a  TSR  and  communicate  with  it.  A  program  communi¬ 
cates  with  a  TSR  by  placing  an  identification  value  in  AH  and  a  function  number  in  AL  and 
issuing  an  Interrupt  2FH.  The  TSR’s  Interrupt  2FH  handler  compares  the  value  in  AH  to  its 
own  predetermined  ID  value.  If  they  match,  the  TSR’s  handler  keeps  control  and  performs 
the  function  specified  in  the  AL  register.  If  they  do  not  match,  the  TSR’s  handler  relin¬ 
quishes  control  to  the  previously  installed  Interrupt  2FH  handler.  (Multiplex  ID  values  OOH 
through  7FH  are  reserved  for  use  by  MS-DOS;  therefore,  user  multiplex  numbers  should  be 
in  the  range  80H  through  OFFH.) 

The  handler  in  the  following  example  recognizes  only  one  function,  corresponding  to 
AL  =  OOH.  In  this  case,  the  handler  returns  the  value  OFFH  in  AL,  signifying  that  the  han¬ 
dler  is  indeed  resident  in  RAM.  Thus,  a  program  can  detect  the  presence  of  the  handler  by 
executing  Interrupt  2FH  with  the  handler’s  ID  value  in  AH  and  OOH  in  AL. 

mov  ah,MultiplexID 

mov  al,00H 

int  2FH 

cmp  al,0FFH 

je  Alreadyinstalled 

To  ensure  that  the  identification  byte  is  unique,  its  value  should  be  determined  at  the 
time  the  TSR  is  installed.  One  way  to  do  this  is  to  pass  the  value  to  the  TSR  program  as  a 
command-line  parameter  when  the  TSR  program  is  installed.  Another  approach  is  to  place 
the  identification  value  in  an  environment  variable.  In  this  way,  the  value  can  be  found  in 
the  environment  of  both  the  TSR  and  any  other  program  that  calls  Interrupt  2FH  to  verify 
the  TSR’s  presence. 
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In  practice,  the  multiplex  interrupt  can  also  be  used  to  pass  information  to  and  from  a 
RAM-resident  program  in  the  CPU  registers,  thus  providing  a  mechanism  for  a  program  to 
share  control  or  status  information  with  a  TSR. 


TSR  Programming  Examples 

One  effective  way  to  become  familiar  with  TSRs  is  to  examine  functional  programs. 
Therefore,  the  subsequent  pages  present  two  examples:  a  simple  passive  TSR  and  a  more 
complex  active  TSR. 

HELLO.ASM 

The  “bare-bones”  TSR  in  Figure  11-3  is  a  passive  TSR.  The  RAM-resident  application,  which 
simply  displays  the  message  Hello,  World,  is  invoked  by  executing  a  software  interrupt. 
This  example  illustrates  the  fundamental  interactions  among  a  RAM-resident  program, 
MS-DOS,  and  programs  that  execute  after  the  installation  of  the  RAM-resident  utility. 


;  Name : 

hello 

;  Description: 

This  RAN 

-resident 

(terminate-and-stay-resident ) 

displays 

the  message  "Hello,  World"  in  response 

software 

interrupt . 

;  Comments: 

Assemble 

and  link 

to  create  HELLO.EXE. 

Execute 

HELLO.EXE 

to  make  resident. 

Execute 

INT  64h 

to  display  the  message. 

TSRInt 

EQU 

64h 

STDOUT 

EQU 

1 

RESIDENT_TEXT 

SEGMENT 

byte  public  'CODE' 

ASSUME 

cs : RESIDENT_TEXT, ds : RESIDENT_DATA 

TSRAction 

PROC 

far 

sti 

;  enable  interrupts 

push 

ds 

;  preserve  registers 

push 

ax 

push 

bx 

push 

cx 

push 

dx 

Figure  11-3-  HELLO.ASM,  a  passive  TSR. 


(more) 
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mov 
mov 
mov 
mov 
mov 
mov 

int  21h 

pop  dx 

pop  cx 

pop  bx 

pop  ax 

pop  ds 

iret 

TSRAction  ENDP 

RESIDENT_TEXT  ENDS 


;  DS:DX  ->  message 
;  CX  =  length 

;  BX  =  file  handle 

;  AH  =  INT  21 H  function  40H 

;  (Write  File) 

;  display  the  message 

;  restore  registers  and  exit 


dx,seg  RESIDENT_DATA 
ds,  dx 

dx, offset  Message 
cx,  1  6 
bx,STDOUT 
ah,40h 


RESIDENT_DATA  SEGMENT  word  public  'DATA' 

Message  DB  ODh, OAh, ' Hello,  World' , ODh, OAh 

RESIDENT_DATA  ENDS 


TRANSIENT_TEXT  SEGMENT  para  public  'TCODE' 

ASSUME  CS : TRANSIENT_TEXT, ss : TRANSIENT-STACK 

far  ;  At  entry:  CS:IP  ->  SnapTSR 

;  SS:SP  ->  stack 

;  DS,ES  ->  PSP 

TSR' s  interrupt  handler 

mov  ax,seg  RESIDENT— TEXT 

mov  ds,ax 

mov  dx, offset  RESIDENT— TEXT: TSRAction 

mov  al,TSRInt 

mov  ah,25h 

int  21  h 


HelloTSR  PROC 

;  Install  this 


;  Terminate  and  stay  resident 
mov  dx,cs 


mov 

sub 


Figure  11-3.  Continued. 


ax,  es 
dx,  ax 


;  DX  =  paragraph  address  of  start  of 
;  transient  portion  (end  of  resident 
;  portion) 

;  ES  =  PSP  segment 
;  DX  =  size  of  resident  portion 


(more) 
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mov 

ax, 31 OOh 

;  AH  =  INT 

21 H  function  number  (TSR) 

;  AL  =  OOH 

(return  code) 

int 

21h 

HelloTSR 

ENDP 

TRANSIENT-TEXT 

ENDS 

TRANSIENT-STACK 

SEGMENT 

word  stack 

'TSTACK' 

DB  80h  dup(?) 

TRANSIENT_STACK  ENDS 


END  HelloTSR 

Figure  11-3.  Continued. 

The  transient  portion  of  the  program  (in  the  segments  TRANSIENT^TEXT  and 
TRANSIENT^STACK)  runs  only  when  the  file  HELLO.EXE  is  executed.  This  installation 
code  updates  an  interrupt  vector  to  point  to  the  resident  application  (the  procedure 
TSRAction)  and  then  calls  Interrupt  21H  Function  31H  to  terminate  execution,  leaving  the 
segments  RESIDENT^TEXT  and  RESIDENT_DATA  in  RAM. 

The  order  in  which  the  code  and  data  segments  appear  in  the  listing  is  important.  It 
ensures  that  when  the  program  is  executed  as  a  .EXE  file,  the  resident  code  and  data  are 
placed  in  memory  at  lower  addresses  than  the  transient  code  and  data.  Thus,  when  Inter¬ 
rupt  21H  Function  31H  is  called,  the  memory  occupied  by  the  transient  portion  of  the  pro¬ 
gram  is  freed  without  disrupting  the  code  and  data  in  the  resident  portion. 

The  RAM  containing  the  resident  portion  of  the  utility  is  left  intact  by  MS-DOS  during 
subsequent  execution  of  other  programs.  Thus,  after  the  TSR  has  been  installed,  any  pro¬ 
gram  that  issues  the  software  interrupt  recognized  by  the  TSR  (in  this  example.  Interrupt 
64H)  will  transfer  control  to  the  routine  TSRAction,  which  uses  Interrupt  21H  Function 
40H  to  display  a  simple  message  on  standard  output. 

Part  of  the  reason  this  example  is  so  short  is  that  it  performs  no  error  checking  A  truly  reli¬ 
able  version  of  the  program  would  check  the  version  of  MS-DOS  in  use,  verify  that  the  pro¬ 
gram  was  not  already  installed  in  memory,  and  chain  to  any  previously  installed  interrupt 
handlers  that  use  the  same  interrupt  vector.  (The  next  program,  SNAP.ASM,  illustrates 
these  techniques.)  However,  the  primary  reason  the  program  is  small  is  that  it  makes  the 
basic  assumption  that  MS-DOS,  the  ROM  BIOS,  and  the  hardware  interrupts  are  all  stable 
at  the  time  the  resident  utility  is  executed. 

SNAP.ASM 

The  preceding  assumption  is  a  reliable  one  in  the  case  of  the  passive  TSR  in  Figure  11-3, 
which  executes  only  when  it  is  explicitly  invoked  by  a  software  interrupt.  However,  the 
situation  is  much  more  complicated  in  the  case  of  the  active  TSR  in  Figure  11-4.  This 
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program  is  relatively  long  because  it  makes  no  assumptions  about  the  stability  of  the 
operating  environment.  Instead,  it  monitors  the  status  of  MS-DOS,  the  ROM  BIOS,  and  the 
hardware  interrupts  to  decide  when  the  RAM-resident  application  can  safely  execute. 


Name :  snap 

Description:  This  RAM-resident  (terminate-and-stay-resident )  utility 

produces  a  video  "snapshot"  by  copying  the  contents  of  the 
video  regeneration  buffer  to  a  disk  file.  It  may  be  used 
in  80-column  alphanumeric  video  modes  on  IBM  PCs  and  PS/2s. 

Comments:  Assemble  and  link  to  create  SNAP.EXE. 

Execute  SNAP.EXE  to  make  resident. 

Press  Alt-Enter  to  dump  current  contents  of  video  buffer 
to  a  disk  file. 


MultiplexID 

EQU 

OCAh 

;  unique  INT  2FH  ID  value 

TSRStackSize 

EQU 

lOOh 

;  resident  stack  size  in  bytes 

KB_FLAG 

EQU 

17h 

;  offset  of  shift-key  status  flag  in 
;  ROM  BIOS  keyboard  data  area 

KBIns 

EQU 

80h 

;  bit  masks  for  KB_FLAG 

KBCaps 

EQU 

.  40h 

KBNum 

EQU 

20h 

KBScroll 

EQU 

lOh 

KBAlt 

EQU 

8 

KBCtl 

EQU 

4 

KBLeft 

EQU 

2 

KBRight 

EQU 

1 

SCEnter 

EQU 

ICh 

CR 

EQU 

ODh 

LF 

EQU 

OAh 

TRUE 

EQU 

-1 

FALSE 

EQU 

PAGE 

0 

RAM-resident  routines 


RESIDENT_GROUP  GROUP  RESIDENT_TEXT, RESIDENT_DATA, RESIDENT_STACK 

Figure  11-4.  SNAP.  ASM,  a  video  snapshot  TSR.  (more) 
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RESIDENT_TEXT  SEGMENT  byte  public  *CODE' 

ASSUME  cs : RESIDENT-GROUP, ds : RESIDENT-GROUP 


System  verification  routines 


VerifyDOSState 


VerifyDOSState 


PROC 

near 

;  Returns:  carry  flag  set  if  MS-DOS 

;  is  busy 

push 

ds 

;  preserve  these  registers 

push 

bx 

push 

ax 

Ids 

bx, cs : ErrorModeAddr 

mov 

ah, [bx] 

;  AH  =  ErrorMode  flag 

Ids 

bx, cs : InDOSAddr 

mov 

al, [bx] 

;  AL  =  InDOS  flag 

xor 

bx,  bx 

;  BH  =  OOH,  BL  =  OOH 

cmp 

bl,cs:InISR28 

;  carry  flag  set  if  INT  28H  handler 
;  is  running 

rcl 

bl,01h 

;  BL  =  01 H  if  INT  28H  handler  is  running 

cmp 

bx,  ax 

;  carry  flag  zero  if  AH  =  OOH 
f  and  AL  <=  BL 

pop 

ax 

;  restore  registers 

pop 

bx 

pop 

ret 

ENDP 

ds 

VerifyIntState  PROC  near 


;  Returns:  carry  flag  set  if  hardware 

;  or  ROM  BIOS  unstable 


push  ax 


;  preserve  AX 


;  Verify  hardware  interrupt  status  by  interrogating  Intel  8259A  Programmable 
;  Interrupt  Controller 


mov 

ax, 00001011b 

;  AH  =  0 

;  AL  =  0CW3  for  Intel  8259A  (RR  =  1, 

;  RIS  =  1 ) 

out 

20h,al 

;  request  8259A's  in-service  register 

jmp 

short  LI  0 

;  wait  a  few  cycles 

L10: 

in 

al,20h 

;  AL  =  hardware  interrupts  currently 
;  being  serviced  (bit  =  1  if  in-service) 

Figure  11-4. 

Continued. 
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cmp  ah,al 

jc  L1 1  ;  exit  if  any  hardware  interrupts  still 

;  being  serviced 


;  Verify  status  of  ROM  BIOS  interrupt  handlers 


xor 

al,  al 

;  AL  =  OOH 

cmp 

al, cs : InISRS 

jc 

L1 1 

;  exit  if  currently  in  INT  OSH  handler 

cmp 

al,cs:InISR9 

jc 

L11 

;  exit  if  currently  in  INT  09H  handler 

cmp 

al,  cs : InISRI 0 

jc 

LI  1 

;  exit  if  currently  in  INT  1 0H  handler 

cmp 

al, cs : InISRI 3 

;  set  carry  flag  if  currently  in 
;  INT  13H  handler 

LI  1  : 

pop 

ax 

;  restore  AX  and  return 

ret 

Verifyint State 

ENDP 

VerifyTSRState 

PROC 

near 

;  Returns:  carry  flag  set  if  TSR 

;  inactive 

rol 

cs :HotFlag, 1 

;  carry  flag  set  if  (HotFlag  =  TRUE) 

cmc 

;  carry  flag  set  if  (HotFlag  =  FALSE) 

jc 

L20 

;  exit  if  no  hot  key 

ror 

cs : ActiveTSR, 1 

;  carry  flag  set  if  (ActiveTSR  =  TRUE) 

jc 

L20 

;  exit  if  already  active 

call 

VerifyDOSState 

jc 

L20 

;  exit  if  MS-DOS  unstable 

call 

Verify IntState 

;  set  carry  flag  if  hardware  or  BIOS 
;  unstable 

L20: 

ret 

VerifyTSRState 

ENDP 

PAGE 

System  monitor  routines 


ISR5  PROC 

far 

;  INT  OSH  handler 

;  (ROM  BIOS  print  screen) 

inc 

cs : InISRS 

;  increment  status  flag 

Figure  11-4.  Continued. 
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pushf 

cli 

call 

cs:PrevISR5  ; 

chain  to  previous  INT  OSH  handler 

dec 

cs:InISR5  ; 

decrement  status  flag 

iret 

ISR5 

ENDP 

ISR8 

PROC 

far 

INT  08H  handler  (timer  tick,  IRQO) 

pushf 

cli 

call 

cs:PrevISR8  ; 

chain  to  previous  handler 

cmp 

cs:InISR8,0 

jne 

L31 

exit  if  already  in  this  handler 

inc 

cs:InISR8  ; 

increment  status  flag 

sti 

; 

interrupts  are  ok 

call 

VerifyTSRState 

jc 

L30 

jump  if  TSR  is  inactive 

mov 

byte  ptr  cs : Act iveTSR, TRUE 

call 

TSRapp 

mov 

byte  ptr  cs : Act iveTSR, FALSE 

L30: 

dec 

cs : InISR8 

L31  : 

iret 

ISR8 

ENDP 

ISR9 

PROC 

far  ; 

INT  09H  handler 

(keyboard  interrupt  IRQ1 ) 

push 

ds 

preserve  these  registers 

push 

ax 

push 

bx 

push 

cs 

pop 

ds  ; 

DS  ->  RESIDENT_GROUP 

in 

al,60h  ; 

AL  =  current  scan  code 

pushf 

cli 

simulate  an  INT 

call 

ds:PrevISR9  ; 

let  previous  handler  execute 

Figure  11-4.  Continued. 
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mov 

ah, ds : InISR9 

;  if  already  in  this  handler  . . 

or 

ah, ds :HotFlag 

;  . .  or  currently  processing  hot 

jnz 

L43 

;  . .  jump  to  exit 

inc 

ds: InISR9 

;  increment  status  flag 

sti 

;  now  interrupts  are  ok 

;  Check  scan  code  sequence 


cmp 

ds : HotSeqLen, 0 

je 

L40 

jump  if  no  hot  sequence  to  match 

mov 

bx, ds : Hot Index 

cmp 

al, [bx+Hot Sequence]  ;  test  scan  code  sequence 

jne 

L41 

jump  if  no  match 

inc 

bx 

cmp 

bx, ds : HotSeqLen 

jb 

L42 

jump  if  not  last  scan  code  to  match 

;  Check  shift-key  state 

L40: 

push 

ds 

mov 

ax, 40h 

mov 

ds , ax  ; 

DS  ->  ROM  BIOS  data  area 

mov 

al,ds: [KB_FLAG]  ; 

AH  =  ROM  BIOS  shift-key  flags 

pop 

ds 

and 

al,ds:HotKBMask  ; 

AL  =  flags  AND  "don't  care"  mask 

cmp 

al,ds:HotKBFlag 

jne 

L42 

jump  if  shift  state  does  not  match 

;  Set 

flag  when  hot  key 

is  found 

mov 

byte  ptr  ds : HotFlag, TRUE 

L41  : 

xor 

bx , bx  ; 

reinitialize  index 

L42: 

mov 

ds : Hot Index, bx  ; 

update  index  into  sequence 

dec 

ds:InISR9 

decrement  status  flag 

L43: 

pop 

bx  ; 

restore  registers  and  exit 

pop 

ax 

pop 

ds 

iret 

ISR9 

ENDP 

Figure  11-4.  Continued. 
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ISR1  0 

PROC 

far 

inc 

cs : InISRI 0 

pushf 

cli 

call 

cs  rPrevISRI 0 

dec 

cs : InISRI 0 

iret 

ISR1  0 

ENDP 

ISR1  3 

PROC 

far 

inc 

cs: InISRI 3 

pushf 

cli 

call 

cs : PrevISRI 3 

pushf 

dec 

popf 

cs: InISRI 3 

sti 

ret 

2 

ISR13 

ENDP 

;  INT  10H  handler  (ROM  BIOS  video  I/O) 
;  increment  status  flag 


;  chain  to  previous  INT  1 0H  handler 
;  decrement  status  flag 


;  INT  13H  handler 
;  (ROM  BIOS  fixed  disk  I/O) 
;  increment  status  flag 


;  chain  to  previous  INT  1 3H  handler 

;  preserve  returned  flags 
;  decrement  status  flag 
;  restore  flags  register 

;  enable  interrupts 

;  simulate  IRET  without  popping  flags 


ISR1B  PROC  far  ;  INT  1 BH  trap  (ROM  BIOS  Ctrl-Break) 

mov  byte  ptr  cs : Trapi B, TRUE 
iret 

ISR1B  ENDP 


ISR23  PROC  far  ;  INT  23H  trap  (MS-DOS  Ctrl-C) 

mov  byte  ptr  cs :Trap23, TRUE 
iret 

ISR23  ENDP 


ISR24  •  PROC 

mov 

Figure  11-4.  Continued. 


far  ;  INT  24H  trap  (MS-DOS  critical  error) 

byte  ptr  cs :Trap24, TRUE 

(more) 
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xor 

cmp 

je 

al,al  ; 
cs :Ma jorVersion, 2 
L50 

AL  =  OOH  (MS-DOS  2.x) : 

;  ignore  the  error 

mov 

al,3 

AL  =  03H  (MS-DOS  3.x)  : 

fail  the  MS-DOS  call  in  which 

the  critical  error  occurred 

L50: 

iret 

ISR24 

ENDP 

ISR28 

PROC 

pushf 

cli 

call 

far 

cs:PrevISR28 

INT  28H  handler 

(MS-DOS  idle  interrupt) 

chain  to  previous  INT  28H  handler 

cmp 

jne 

cs:InISR28,0 

L61 

exit  if  already  inside  this  handler 

inc 

cs:InISR28 

increment  status  flag 

call 

jc 

VerifyTSRState 
L60  ; 

:  jump  if  TSR  is  inactive 

mov 

call 

mov 

byte  ptr  cs : Act iveTSR, TRUE 

TSRapp 

byte  ptr  cs :ActiveTSR, FALSE 

L60: 

dec 

cs:InISR28 

decrement  status  flag 

L61  : 

iret 

ISR28 

ENDP 

ISR2F 

PROC 

far 

INT  2FH  handler 

(MS-DOS  multiplex  interrupt) 

Caller:  AH  =  handler  ID 

AL  =  function  number 

Returns  for  function  0:  AL  =  OFFH 
for  all  other  functions:  nothing 

cmp 

je 

ah,MultiplexID 

L70 

jump  if  this  handler  is  requested 

jmp 

cs:PrevISR2F 

chain  to  previous  INT  2FH  handler 

Figure  11-4.  Continued. 
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L70:  test  al,al 

jnz  MultiplexIRET  ;  jump  if  reserved  or  undefined  function 

;  Function  0:  get  installed  state 

mov  al,0FFh  ;  AL  =  OFFH  (this  handler  is  installed) 

MultiplexIRET:  iret  ;  return  from  interrupt 

ISR2F  ENDP 

PAGE 

;  Auxlnt21 — sets  ErrorMode  while  executing  INT  21 H  to  force  use  of  the 
;  AuxStack  instead  of  the  lOStack. 


Auxlnt21 


Auxlnt21 


Int21 V 


PROC  near 


;  Caller:  registers  for  INT  21 H 

;  Returns:  registers  from  INT  21 H 


push 

ds 

push 

bx 

Ids 

bx, ErrorModeAddr 

inc 

byte  ptr  [bx]  ; 

ErrorMode  is  now  nonzero 

pop 

bx 

pop 

ds 

int 

21h 

perform  MS-DOS  function 

push 

ds 

push 

bx 

Ids 

bx, ErrorModeAddr 

dec 

byte  ptr  [bx]  ; 

restore  ErrorMode 

pop 

bx 

pop 

ds 

ret 

ENDP 

PROC 

near 

;  perform  INT  21 H  or  Auxlnt21, 
;  depending  on  MS-DOS  version 

cmp 

DOSVersion, 30Ah 

jb 

L80 

;  jump  if  earlier  than  3.1 

int 

21h 

;  versions  3.1  and  later 

ret 


Figure  11-4.  Continued. 
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L80:  call  Auxlnt21  ;  versions  earlier  than  3.1 

ret 

Int21v  ENDP 

PAGE 


;  RAM-resident  application 


TSRapp  PROC  near 

/  Set  up  a  safe  stack 


push 

ds 

;  save 

previous  DS  on  previous  stack 

push 

cs 

pop 

ds 

;  DS  -> 

RESIDENT_GROUP 

mov 

PrevSP, sp 

;  save 

previous  SS:SP 

mov 

PrevSS, ss 

mov 

ss,TSRSS 

;  SS:SP 

->  RESIDENT_STACK 

mov 

sp,TSRSP 

push 

es 

;  preserve  remaining  registers 

push 

ax 

push 

bx 

push 

cx 

push 

dx 

push 

si 

push 

di 

push 

bp 

cld 

;  clear 

direction  flag 

;  Set  break  and  critical  error  traps 


mov 

cx, NTrap 

mov 

si, of fset 

RESIDENT_GROUP : StartTrapList 

lodsb 

;  AL  =  interrupt  number 
;  DS:SI  ->  byte  past  interrupt  number 

mov 

byte  ptr 

[si], FALSE  ;  zero  the  trap  flag 

push 

ax 

;  preserve  AX 

mov 

ah, 35h 

;  INT  21 H  function  35H 
;  (get  interrupt  vector) 

int 

21h 

;  ES:BX  =  previous  interrupt  vector 

mov 

[si+1 ] ,bx 

;  save  offset  and  segment  . . 

mov 

[si+3] ,es 

;  . .  of  previous  handler 

Figure  11-4.  Continued. 
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pop 

ax 

;  AL  =  interrupt  number 

mov 

dx, [si+5] 

;  DS:DX  ->  this  TSR' s  trap 

mov 

ah,25h 

;  INT  21 H  function  25H 

int 

21h 

;  (set  interrupt  vector) 

add 

si,  7 

;  DS:SI  ->  next  in  list 

loop 

L90 

;  Disable  MS-DOS  break  checking  during  disk  I/O 

mov  ax,3300h  ;  AH  =  INT  21 H  function  number 

;  AL  =  OOH  (request  current  break  state) 

int  21 h  ;  DL  =  current  break  state 

mov  PrevBreak,dl  ;  preserve  current  state 

xor  dl,dl 

mov  ax,3301h 

int  21h 

;  Preserve  previous  extended  error  information 
cmp  DOSVersion, 30Ah 

jb  L91  ;  jump  if  MS-DOS  version  earlier 

;  than  3 . 1 

push  ds  ;  preserve  DS 

xor  bx,bx  ;  BX  =  OOH  (required  for  function  59H) 

mov  ah,59h  ;  INT  21 H  function  59H 

call  Int21v  ;  (get  extended  error  info) 

mov  cs :PrevExtErrDS, ds 

pop  ds  ^ 

mov  PrevExtErrAX, ax  ;  preserve  error  information 

mov  PrevExtErrBX,bx  ;  in  data  structure 

mov  PrevExtErrCX, cx 

mov  PrevExtErrDX, dx 

mov  PrevExtErrSI, si 

mov  PrevExtErrDI, di 

mov  PrevExtErrES, es 


;  Inform  MS-DOS  about  current  PSP 


L91  : 

mov 

call 

ah, 51h 

Int21 V 

;  INT  21 H  function  51 H 
;  BX  =  foreground  PSP 

(get 

PSP  address) 

mov 

PrevPSP,bx 

;  preserve  previous  PSP 

mov 

mov 

call 

bx,TSRPSP 
ah, 50h 

Int21 V 

;  BX  =  resident  PSP 

;  INT  21 H  function  50H 

(set 

PSP  address) 

Figure  11-4. 

Continued. 
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;  DL  =  OOH  (disable  disk  I/O  break 
;  checking) 

;  AL  =  01 H  (set  break  state) 
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;  Inform  MS-DOS  about  current  DTA  (not  really  necessary  in  this  application 
/because  DTA  is  not  used) 


mov  ah^2Fh 

int  21 h 

mov  PrevDTAoffs,bx 

mov  PrevDTAseg, es 

push  ds 

mov  ds,TSRPSP 

mov  dx,80h 

mov  ah,1Ah 

int  21 h 

pop  ds 

;  Open  a  file,  write  to  it,  and  close  : 

mov  ax,0E07h 

int  1 0h 


;  INT  21 H  function  2FH 
;  (get  DTA  address)  into  ES:BX 


;  preserve  DS 

;  DS:DX  ->  default  DTA  at  PSP:0080H 
;  INT  21 H  function  1AH 
;  (set  DTA  address) 

;  restore  DS 


;  AH  =  INT  1 0H  function  number 
;  (write  teletype) 

;  AL  =  07H  (bell  character) 

;  emit  a  beep 


mov  dx, offset  RESIDENT_GROUP : SnapFile 


mov 

ah,3Ch 

mov 

CX,  0 

int 

21h 

jc 

L94 

push 

ax 

; 

mov 

ah, OFh 

; 

int 

lOh 

pop 

bx 

' 

cmp 

ah,  80 

jne 

L93 

mov 

dx, 0B800h 

; 

cmp 

al,3 

jbe 

L92 

cmp 

al,7 

jne 

L93 

mov 

dx, OBOOOh 

push 

ds 

mov 

ds,  dx 

xor 

dx,  dx 

mov 

CX, 80*25*2 

mov 

ah,40h 

Figure  11-4.  Continued. 


INT  21 H  function  3CH 
(create  file  handle) 
file  attribute 

jump  if  file  not  opened 

push  file  handle 

INT  10H  function  OFH  (get  video  status) 
AL  =  video  mode  number 
AH  =  number  of  character  columns 
BX  =  file  handle 

jump  if  not  80-column  mode 
DX  =  color  video  buffer  segment 
jump  if  color  alphanumeric  mode 


jump  if  not  monochrome  mode 

DX  =  monochrome  video  buffer  segment 


DS:DX  ->  start  of  video  buffer 
CX  =  number  of  bytes  to  write 
INT  21 H  function  40H  (write  file) 
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int  21 h 

pop  ds 


L93: 

mov 

ah,3Eh  ; 

INT  21H  function  3EH  (close  file) 

int 

21h 

mov 

ax,0E07h  ; 

emit  another  beep 

int 

lOh 

;  Restore 

previous  DTA 

L94 : 

push 

ds  ; 

preserve  DS 

Ids 

dx,PrevDTA  ; 

DS:DX  ->  previous  DTA 

mov 

ah , 1 Ah  ; 

INT  21 H  function  1AH  (set  DTA  address) 

int 

21h 

pop 

ds 

;  Restore 

previous  PSP 

mov 

bx,PrevPSP  ; 

BX  =  previous  PSP 

mov 

ah,50h  ; 

INT  21 H  function  50H 

call 

Int21v  ; 

(set  PSP  address) 

;  Restore 

previous  extended  error  information 

mov 

ax, DOSVersion 

cmp 

ax, 30Ah 

jt> 

L95 

jump  if  MS-DOS  version  earlier  than  3.1 

cmp 

ax, OAOOh 

jae 

L95 

jump  if  MS  OS/2-DOS  3.x  box 

mov 

dx, offset  RESIDENT_GROUP : PrevExtErrInf o 

mov 

ax, SDOAh 

int 

21h 

(restore  extended  error  information) 

;  Restore 

previous  MS-DOS  break  checking 

L95: 

mov 

dl,PrevBreak  ; 

DL  =  previous  state 

mov 

ax, 3301h 

int 

21h 

;  Restore 

previous  break  and  critical  error  traps 

mov 

cx,NTrap 

mov 

si , offset  RESIDENT_GROUP : StartTrapList 

push 

ds  ; 

preserve  DS 

L96: 

lods 

byte  ptr  cs ; [si]  , 

?  AL  =  interrupt  number 

ES;SI  ->  byte  past  interrupt  number 

Ids 

dx, cs ; [si+1 ]  ; 

DS:DX  ->  previous  handler 

mov 

ah,25h  ; 

INT  21 H  function  25H 

int 

Figure  11-4.  Continued. 

21h 

(set  interrupt  vector) 
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add 

si,  7 

;  DS:SI  ->  next  in  list 

loop 

L96 

pop 

ds 

;  restore  DS 

;  Restore  all  registers 

pop  bp 

pop  di 

pop  si 

pop  dx 

pop  cx 

pop  bx 

pop  ax 

pop  es 

mov  ss,PrevSS  ;  SS:SP  ->  previous  stack 

mov  sp,PrevSP 

pop  ds  ;  restore  previous  DS 

;  Finally,  reset  status  flag  and  return 

mov  byte  ptr  cs :HotFlag, FALSE 

ret 

TSRapp  ENDP 

RESIDENT_TEXT  ENDS 


RESIDENT_DATA  SEGMENT  word  public  *DATA’ 


ErrorModeAddr 

DD 

? 

;  address  of 

MS-DOS  ErrorMode  flag 

InDOSAddr 

DD 

7 

;  address  of 

MS-DOS  InDOS  flag 

NISR 

DW 

(EndlSRList-StartlSRList) /S  ; 

:  number  of  installed  ISRs 

StartlSRList 

DB 

05h 

;  INT  number 

InISRS 

DB 

FALSE 

;  flag 

PrevISRS 

DD 

? 

;  address  of 

previous  handler 

DW 

offset 

RESIDENT_GROUP : ISR5 

DB 

OSh 

InISRS 

DB 

FALSE 

PrevISRS 

DD 

7 

DW 

offset 

RESIDENT_GROUP : ISRS 

DB 

09h 

InISR9 

DB 

FALSE 

PrevISR9 

DD 

7 

DW 

offset 

RESIDENT_GROUP : ISR9 

DB 

lOh 

InISRI 0 

DB 

FALSE 

Figure  11-4.  Continued.  (more) 
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PrevISRI 0 

DD 

7 

DW 

offset  RESIDENT-GROUP:  I  SRI  0 

DB 

13h 

InISR13 

DB 

FALSE 

PrevISRI 3 

DD 

7 

DW 

offset  RESIDENT-GROUP : ISR1 3 

DB 

28h 

InISR28 

DB 

FALSE 

PrevISR28 

DD 

7 

DW 

offset  RESIDENT-GROUP: I SR2 8 

DB 

2Fh 

InISR2F 

DB 

FALSE 

PrevISR2F 

DD 

7 

DW 

offset  RESIDENT-GROUP : ISR2F 

EndlSRList 

LABEL 

BYTE 

TSRPSP 

DW 

?  ;  resident  PSP 

TSRSP 

DW 

TSRStackSize  ;  resident  SS:SP 

TSRSS 

DW 

seg  RESIDENT-STACK 

PrevPSP 

DW 

?  ;  previous  PSP 

PrevSP 

DW 

?  ;  previous  SS:SP 

PrevSS 

DW 

7 

Hot Index 

DW 

0  ;  index  of  next  scan  code  in  sequence 

HotSeqLen 

DW 

EndHotSeq-HotSequence  ;  length  of  hot-key  sequence 

HotSequence 

DB 

SCEnter  ;  hot  sequence  of  scan  codes 

EndHotSeq 

LABEL 

BYTE 

HotKBFlag 

DB 

KBAlt  ;  hot  value  of  ROM  BIOS  KB-FLAG 

HotKBMask 

DB 

(KBIns  OR  KBCaps  OR  KBNum  OR  KBScroll)  XOR  OFFh 

HotFlag 

DB 

FALSE 

ActiveTSR 

DB 

FALSE 

DOSVersion 

LABEL 

WORD 

DB 

?  ;  minor  version  number 

Ma jorVersion 

DB 

?  ;  major  version  number 

;  The  following 

data  is 

used  by  the  TSR  application: 

NTrap 

DW 

(EndTrapList-StartTrapList) /8  ;  number  of  traps 

StartTrapList 

DB 

IBh 

Trapi B 

DB 

FALSE 

PrevISRI B 

DD 

7 

DW 

offset  RESIDENT-GROUP :ISR1B 

DB 

23h 

Figure  11-4.  Continued. 
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Trap23  DB  FALSE 

PrevISR23  DD  ? 

DW  offset  RESIDENT_GROUP:ISR23 

DB  24h 

Trap24  DB  FALSE 

PrevISR24  DD  ? 

DW  offset  RESIDENT_GROUP:ISR24 

EndTrapList  LABEL  BYTE 

PrevBreak  DB  ?  ;  previous  break-checking  flag 

PrevDTA  LABEL  DWORD  ;  previous  DTA  address 

PrevDTAoffs  DW  ? 

PrevDTAseg  DW  ? 

PrevExtErrInfo  LABEL  BYTE  ;  previous  extended  error  information 

PrevExtErrAX  DW  ? 

PrevExtErrBX  DW  ? 

PrevExtErrCX  DW  ? 

PrevExtErrDX  DW  ? 

PrevExtErrSI  DW  ? 

PrevExtErrDI  DW  ? 

PrevExtErrDS  DW  ? 

PrevExtErrES  DW  ? 

DW  3  dup(O) 

SnapFile  DB  '\snap.irag'  ;  output  filename  in  root  directory 

RESIDENT_DATA  ENDS 

RESIDENT-STACK  SEGMENT  word  stack  'STACK' 

DB  TSRStackSize  dup(?) 

RESIDENT-STACK  ENDS 

PAGE 


;  Transient  installation  routines 


TRANSIENT-TEXT  SEGMENT  para  public  'TCODE' 

ASSUME  cs : TRANSIENT-TEXT, ds : RESIDENT-DATA, ss : RESIDENT-STACK 


InstallSnapTSR  PROC  far 

Figure  11-4.  Continued. 


At  entry:  CS:IP  ->  InstallSnapTSR 
SS:SP  ->  stack 
DS,ES  ->  PSP 

(more) 
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;  Save  PSP  segment 

mov  ax,seg  RESIDENT_DATA 

mov  ds,ax  ;  DS  ->  RESIDENT-DATA 

mov  TSRPSP,es  ;  save  PSP  segment 

;  Check  the  MS-DOS  version 

call  GetDOSVersion  ;  AH  =  major  version  number 

;  AL  =  minor  version  number 

;  Verify  that  this  TSR  is  not  already  installed 

;  Before  executing  INT  2FH  in  MS-DOS  versions  2.x,  test  whether  INT  2FH 

;  vector  is  in  use.  If  so,  abort  if  PRINT.COM  is  using  it. 

;  (Thus,  in  MS-DOS  2.x,  if  both  this  program  and  PRINT.COM  are  used, 

;  this  program  should  be  made  resident  before  PRINT.COM.) 


cmp 

ah,  2 

ja 

L101 

jump. if  version  3.0  or  later 

mov 

ax,352Fh 

9 

9 

AH  =  INT  21 H  function  number 

AL  =  interrupt  number 

int 

21h 

9 

ES:BX  =  INT  2FH  vector 

mov 

ax,  es 

or 

ax,bx 

; 

jump  if  current  INT  2FH  vector  . . 

jnz 

L100 

. .  is  nonzero 

push 

ds 

mov 

ax, 252Fh 

AH  =  INT  21 H  function  number 

AL  =  interrupt  number 

mov 

dx,seg  RESIDENT. 

-GROUP 

mov 

ds,  dx 

mov 

dx, offset  RESIDENT-GROUP ; Mu It ip lex I RET 

int 

21h 

; 

point  INT  2FH  vector  to  IRET 

pop 

ds 

jmp 

short  LI  03 

jump  to  install  this  TSR 

mov 

ax, OFFOOh 

; 

look  for  PRINT.COM: 

int 

2Fh 

; 

if  resident,  AH  =  print  queue  length, 

otherwise,  AH  is  unchanged 

cmp 

ah,0FFh 

; 

if  PRINT.COM  is  not  resident  . . 

je 

L101 

. .  use  multiplex  interrupt 

mov 

al,1 

call 

FatalError 

; 

abort  if  PRINT.COM  already  installed 

Figure  11-4.  Continued. 
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L101  : 

mov 

ah,MultiplexID 

AH  =  multiplex  interrupt  ID  value 

xor 

al,  al 

AL  =  OOH 

int 

2Fh 

multiplex  interrupt 

test 

al,  al 

jz 

L103 

'• 

jump  if  ok  to  install 

cmp 

al, OFFh 

jne 

L102 

jump  if  not  already  installed 

mov 

al,2 

call 

FatalError 

'* 

already  installed 

L102: 

mov 

al,3 

call 

FatalError 

can't  install 

;  Get 

addresses  of  InDOS  and  ErrorMode 

flags 

L103: 

call 

GetDOSFlags 

;  Install  this  TSR' s  interrupt  handlers 

push 

es 

preserve  PSP  segment 

mov 

cx,NISR 

mov 

si, offset  StartlSRList 

L104: 

lodsb 

f 

AL  =  interrupt  number 

DS:SI  ->  byte  past  interrupt  number 

push 

ax 

f 

preserve  AX 

mov 

ah,35h 

f 

INT  21 H  function  35H 

int 

21h 

/ 

ES:BX  =  previous  interrupt  vector 

mov 

[si+1 ] ,bx 

/ 

save  offset  and  segment  . . 

mov 

[si+3] , es 

9 

. .  of  previous  handler 

pop 

ax 

; 

AL  =  interrupt  number 

push 

ds 

; 

preserve  DS 

mov 

dx, [si+5] 

mov 

bx,seg  RESIDENT 

-GROUP 

mov 

ds,  bx 

; 

DS:DX  ->  this  TSR' s  handler 

mov 

ah,25h 

; 

INT  21 H  function  25H 

int 

21h 

; 

(set  interrupt  vector) 

pop 

ds 

; 

restore  DS 

add 

si,  7 

; 

DS;SI  ->  next  in  list 

loop 

LI  04 

;  Free 

the  environment 

pop 

es 

; 

ES  =  PSP  segment 

push 

es 

; 

preserve  PSP  segment 

mov 

es, es : [2Ch] 

; 

ES  =  segment  of  environment 

Figure  11-4.  Continued. 
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mov 

int 

ah,49h 

21h 

;  Terminate  and 

stay 

resident 

pop 

mov 

ax  ; 

dx,cs  ; 

sub 

dx,ax  ; 

mov 

ax,3100h  ; 

int 

21h 

InstallSnapTSR 

ENDP 

GetDOSVersion 

PROC 

near  ; 

ASSUME  ds:RESIDENT_DATA 

mov 

ah,30h  ; 

int 

cmp 

jb 

21h 

al,2 

L1 10 

xchg 

ah,al  ; 

mov 

DOSVersion, ax  ; 

ret 

LI  10: 

mov 

call 

al,00h 

FatalError 

GetDOSVersion 

GetDOSFlags 

ENDP 

PROC 

near  ; 

ASSUME  ds : RESIDENT_DATA 
;  Get  InDOS  address  from  MS-DOS 


push 

es 

mov 

ah,34h 

int 

21h 

Figure  11-4.  Continued. 


INT  21 H  function  49H 
(free  memory  block) 


AX  =  PSP  segment 

DX  =  paragraph  address  of  start  of 
transient  portion  (end  of  resident 
portion) 

DX  =  size  of  resident  portion 

AH  =  INT  21 H  function  number 
AL  =  OOH  (return  code) 


Caller:  DS  =  seg  RESIDENT_DATA 

ES  =  PSP 

Returns:  AH  =  major  version 

AL  =  minor  version 


INT  21 H  function  30H: 
(get  MS-DOS  version) 


jump  if  versions  1 .x 

AH  =  major  version 
AL  =  minor  version 
save  with  major  version  in 
high-order  byte 


abort  if  versions  1  .x 


Caller:  DS  =  seg  RESIDENT_DATA 

Returns :  InDOSAddr  ->  InDOS 

ErrorModeAddr  ->  ErrorMode 
Destroys:  AX,BX,CX,DI 


INT  21 H  function  number 
ES:BX  ->  InDOS 


(more) 


Section  II:  Programming  in  the  MS-DOS  Environment  'ill 


Part  C:  Customizing  MS-DOS 


mov  word  ptr  InDOSAddr,bx 

mov  word  ptr  InDOSAddr+2, es 

;  Determine  ErrorMode  address 

mov  word  ptr  ErrorModeAddr+2, es  ;  assume  ErrorMode  is 

;  in  the  same  segment 
;  as  InDOS 


mov 

ax, DOSVersion 

cmp 

ax, 30Ah 

jb 

L120 

;  jump  if  MS-DOS  version  earlier 
;  than  3.1  . . 

cmp 

ax, OAOOh 

jae 

L120 

;  ..or  MS  OS/2-DOS  3.x  box 

dec 

bx 

;  in  MS-DOS  3.1  and  later,  ErrorMode 

mov 

word  ptr  ErrorModeAddr, bx  ;  is  just  before  InDOS 

jmp 

short  LI  25 

LI  20:  ;  scan  MS-DOS  segment  for  ErrorMode 


mov  cx,0FFFFh  ;  CX  =  maximum  number  of  bytes  to  scan 

xor  di,di  ;  ES:DI  ->  start  of  MS-DOS  segment 


L121  : 

mov 

ax, word  ptr  cs:LF2  ;  AX  = 

=  opcode  for  INT  28H 

L122: 

repne 

scasb  ;  scan 

for  first  byte  of  fragment 

jne 

LI  26  ;  jump 

if 

not  found 

cmp 

ah,es: [di] 

; 

inspect  second  byte  of  opcode 

jne 

L122 

jump  if  not  INT  28H 

mov 

ax, word  ptr  cs:LF1  +  1 

; 

AX  =  opcode  for  CMP 

cmp 

ax,es:[di] [LF1-LF2] 

jne 

L123 

jump  if  opcode  not  CMP 

mov 

ax,es: [di] [ (LF1-LF2)+2] 

AX  =  offset  of  ErrorMode 

jmp 

short  L124 

in  DOS  segment 

LI  23: 

mov 

ax, word  ptr  cs:LF3  +  1 

• 

AX  =  opcode  for  TEST 

cmp 

ax,es: [di] [LF3-LF4] 

jne 

L121 

jump  if  opcode  not  TEST 

mov 

ax,es:[di] [ (LF3-LF4 ) +2] 

AX  =  offset  of  ErrorMode 

L124: 

mov 

word  ptr  ErrorModeAddr, 

ax 

L125: 

pop 

es 

ret 

Figure  11-4.  Continued.  (more) 
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;  Come  here  if  address  of  ErrorMode  not  found 
L126: 


mov 

call 


al,04h 

FatalError 


Code  fragments  for  scanning  for  ErrorMode  flag 


LFnear 

LABEL 

near  ; 

dummy  labels  for  addressing 

LFbyte 

LABEL 

byte 

LFword 

LABEL 

word 

; 

MS-DOS  versions  earlier  than  3 

LF1  : 

cmp 

ss: LFbyte, 0  ; 

CMP  ErrorMode, 0 

jne 

LFnear 

LF2: 

int 

28h 

; 

MS-DOS  versions  3.1  and  later 

LF3: 

test 

s  s : LFbyte , OFFh  ; 

TEST  ErrorMode, OFFH 

jne 

LFnear 

push 

ss : LFword 

LF4  : 

int 

28h 

GetDOSFlags 

ENDP 

FatalError 

PROC 

near  ; 

Caller:  AL  =  message  number 

; 

ES  =  PSP 

ASSUME 

ds : TRANSIENT-DATA 

push 

ax  ; 

save  message  number  on  stack 

mov 

bx,seg  TRANSIENT-DATA 

mov 

ds,bx 

;  Display  the  requested  message 

mov 

bx, offset  MessageTable 

xor 

ah, ah  ; 

AX  =  message  number 

shl 

ax,1 

AX  =  offset  into  MessageTable 

add 

bx,ax  ; 

DS:BX  ->  address  of  message 

mov 

dx, [bx]  ; 

DS:DX  ->  message 

mov 

ah,09h  ; 

INT  21 H  function  09H  (display 

int 

21h 

display  error  message 

pop 

ax  ; 

AL  =  message  number 

or 

al,  al 

jz 

LI  30 

jump  if  message  number  is  zero 

(MS-DOS  versions  1  .x) 

;  Terminate 

(MS-DOS  2.x 

and  later) 

mov 

ah,4Ch 

INT  21 H  function  4CH 

int 

21h 

(terminate  process  with  return 

Figure  11-4.  Continued. 
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;  Terminate 

(MS-DOS  1 

.X) 

LI  30 

PROC 

far 

push 

es 

;  push  PSP:0000H 

xor 

ax,  ax 

push 

ax 

ret 

;  far  return  (jump  to  PSPrOOOOH) 

L130 

ENDP 

FatalError 

ENDP 

TRANSIENT_TEXT  ENDS 

PAGE 

;  Transient  data  segment 


TRANSIENT_DATA  SEGMENT  word  public  'DATA' 


MessageTable 


DW  MessageO 
DW  Messagel 
DW  Message2 
DW  Messages 
DW  Message4 


;  MS-DOS  version  error 
;  PRINT.COM  found  in  MS-DOS  2.x 
;  already  installed 
;  can't  install 
;  can't  find  flag 


MessageO 

Messagel 

Message2 

Messages 

Message4 


DB  CR,LF, 'TSR  requires  MS-DOS  2.0  or  later  version ', CR, LF, '$  ' 
DB  CR,LF,  'Can' 't  install  TSR:  PRINT.COM  active ', CR, LF,  '$ ' 

DB  CR,LF, 'This  TSR  is  already  installed ', CR, LF, '$ ' 

DB  CR,LF, 'Can' 't  install  this  TSR' , CR, LF, ' $ ' 

DB  CR,LF, 'Unable  to  locate  MS-DOS  ErrorMode  flag' , CR, LF, ' $ ' 


TRANSIENT_DATA  ENDS 


END  InstallSnapTSR 

Figure  11-4.  Continued. 


When  installed,  the  SNAP  program  monitors  keyboard  input  until  the  user  types  the 
hot-key  sequence  Alt-Enter.  When  the  hot-key  sequence  is  detected,  the  monitoring  rou¬ 
tine  waits  until  the  operating  environment  is  stable  and  then  activates  the  RAM-resident 
application,  which  dumps  the  current  contents  of  the  computer’s  video  buffer  into  the  file 
SNAP.IMG.  Figure  11-5  is  a  block  diagram  of  the  RAM-resident  and  transient  components 
of  this  TSR. 


380  The  MS-DOS  Encyclopedia 


Article  11:  Terminate-and-Stay-Resident  Utilities 


Higher  addresses 


Lower  addresses 


Transient  data 

InstallSnapTSR 

Initialization  code  and  data 

RAM-resident  stack 

RAM-resident  data 

TSRapp 

RAM-resident  application 

ISR2F 

INT  2FH  (multiplex  interrupt)  handler 

ISR28 

INT  28H  (DOS  idle  interrupt)  handler 

ISR24 

INT  24H  (critical  error)  handler 

ISR23 

INT  23H  (Control-C)  handler 

ISRIB 

INT  IBH  (Control-Break)  handler 

ISR13 

INT  13H  (BIOS  fixed-disk  I/O)  handler 

ISRIO 

INT  lOH  (BIOS  video  I/O)  handler 

ISR9 

INT  09H  (keyboard  interrupt)  handler 

ISR8 

INT  OSH  (timer  interrupt)  handler 

ISR5 

INT  05H  (BIOS  print  screen)  handler 

TRANSIENT _P AT  A  segment 

TRANSIENT  TEXT  segment 

RESIDENT  STACK  segment 
RESIDENTDATA  segment 


>RESIDENT_TEXT  segment 


Figure  11-5.  Block  structure  of  the  TSR  program  SNAP.EXE  when  loaded  into  memory.  (Compare  with 
Figure  11-1.) 


Installing  the  program 

When  SNAP.EXE  is  run,  only  the  code  in  the  transient  portion  of  the  program  is  executed. 
The  transient  code  performs  several  operations  before  it  finally  executes  Interrupt  21H 
Function  31H  (Terminate  and  Stay  Resident).  First  it  determines  which  MS-DOS  version  is 
in  use.  Then  it  executes  the  multiplex  interrupt  (Interrupt  2FH)  to  discover  whether  the 
resident  portion  has  already  been  installed.  If  an  MS-DOS  version  earlier  than  2.0  is  in  use 
or  if  the  resident  portion  has  already  been  installed,  the  program  aborts  with  an  error 
message. 

Otherwise,  installation  continues.  The  addresses  of  the  InDOS  and  critical  error  flags  are 
saved  in  the  resident  data  segment.  The  interrupt  service  routines  in  the  RAM-resident  por¬ 
tion  of  the  program  are  installed  by  updating  all  relevant  interrupt  vectors.  The  transient 
code  then  frees  the  RAM  occupied  by  the  program’s  environment,  because  the  resident 
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portion  of  this  program  never  uses  the  information  contained  there.  Finally,  the  transient 
portion  of  the  program,  which  includes  the  TRANSIENT^TEXT  and  TRANSIENT_DATA 
segments,  is  discarded  and  the  program  is  terminated  using  Interrupt  21H  Function  31H. 

Detecting  a  hot  key 

The  SNAP  program  detects  the  hot-key  sequence  (Alt-Enter)  by  monitoring  each  keypress. 
On  IBM  PCs  and  PS/2s,  each  keystroke  generates  a  hardware  interrupt  on  IRQl  (Interrupt 
09H).  The  TSR’s  Interrupt  09H  handler  compares  the  keyboard  scan  code  corresponding  to 
each  keypress  with  a  predefined  sequence.  The  TSR’s  handler  also  inspects  the  shift-key 
status  flags  maintained  by  the  ROM  BIOS  Interrupt  09H  handler.  When  the  predetermined 
sequence  of  keypresses  is  detected  at  the  same  time  as  the  proper  shift  keys  are  pressed, 
the  handler  sets  a  global  status  flag  (HotFlag). 

Note  how  the  TSR’s  handler  transfers  control  to  the  previous  Interrupt  09H ISR  before  it 
performs  its  own  work.  If  the  TSR’s  Interrupt  09H  handler  did  not  chain  to  the  previous 
handler(s),  essential  system  processing  of  keystrokes  (particularly  in  the  ROM  BIOS 
Interrupt  09H  handler)  might  not  be  performed. 

Activating  the  application 

The  TSR  monitors  the  status  of  HotFlag  by  regularly  testing  its  value  within  a  timer-tick 
handler.  On  IBM  PCs  and  PS/2s,  the  timer-tick  interrupt  occurs  on  IRQO  (Interrupt  OSH) 
roughly  18.2  times  per  second.  This  hardware  interrupt  occurs  regardless  of  what  else  the 
system  is  doing,  so  an  Interrupt  OSH  ISR  a  convenient  place  to  check  whether  HotFlag  has 
been  set. 

As  in  the  case  of  the  Interrupt  09H  handler,  the  TSR’s  Interrupt  OSH  handler  passes  control 
to  previous  Interrupt  OSH  handlers  before  it  proceeds  with  its  own  work.  This  procedure  is 
particularly  important  with  Interrupt  OSH  because  the  ROM  BIOS  Interrupt  OSH  handler, 
which  maintains  the  system’s  time-of-day  clock  and  resets  the  system’s  Intel  8259A  Pro¬ 
grammable  Interrupt  Controller,  must  execute  before  the  next  timer  tick  can  occur.  The 
TSR’s  handler  therefore  defers  its  own  work  until  control  has  returned  after  previous 
Interrupt  OSH  handlers  have  executed. 

The  only  function  of  the  TSR’s  Interrupt  OSH  handler  is  to  attempt  to  transfer  control  to  the 
RAM-resident  application.  The  routine  VerifyTSRState  performs  this  task.  It  first  examines 
the  contents  of  HotFlag  to  determine  whether  a  hot-key  sequence  has  been  detected.  If 
so,  it  examines  the  state  of  the  MS-DOS  InDOS  and  critical  error  flags,  the  current  status  of 
hardware  interrupts,  and  the  current  status  of  any  non-reentrant  ROM  BIOS  routines  that 
might  be  executing. 

If  HotFlag  is  nonzero,  the  InDOS  and  critical  error  flags  are  both  zero,  no  hardware  inter¬ 
rupts  are  currently  being  serviced,  and  no  non-reentrant  ROM  BIOS  code  has  been  inter¬ 
rupted,  the  Interrupt  OSH  handler  activates  the  RAM-resident  utility.  Otherwise,  nothing 
happens  until  the  next  timer  tick,  when  the  handler  executes  again. 

While  HotFlag  is  nonzero,  the  Interrupt  OSH  handler  continues  to  monitor  system  status 
until  MS-DOS,  the  ROM  BIOS,  and  the  hardware  interrupts  are  all  in  a  stable  state.  Often 
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the  system  status  is  stable  at  the  time  the  hot-key  sequence  is  detected,  so  the  RAM- 
resident  application  runs  immediately.  Sometimes,  however,  system  activities  such  as 
prolonged  disk  reads  or  writes  can  preclude  the  activation  of  the  RAM-resident  utility  for 
several  seconds  after  the  hot-key  sequence  has  been  detected.  The  handler  could  be 
designed  to  detect  this  situation  (for  example,  by  decrementing  HotFlag  on  each  timer 
tick)  and  return  an  error  status  or  display  a  message  to  the  user. 

A  more  serious  difficulty  arises  when  the  MS-DOS  default  command  processor 
(COMMAND.COM)  is  waiting  for  keyboard  input.  In  this  situation.  Interrupt  21H  Function 
OlH  (Character  Input  with  Echo)  is  executing,  so  InDOS  is  nonzero  and  the  Interrupt  OSH 
handler  can  never  detect  a  state  in  which  it  can  activate  the  RAM-resident  utility.  This 
problem  is  solved  by  providing  a  custom  handler  for  Interrupt  28H  (the  MS-DOS  idle  inter¬ 
rupt),  which  is  executed  by  Interrupt  21H  Function  OlH  each  time  it  loops  as  it  waits  for  a 
keypress.  The  only  difference  between  the  Interrupt  28H  handler  and  the  Interrupt  OSH 
handler  is  that  the  Interrupt  28H  handler  can  activate  the  RAM-resident  application  when 
the  value  of  InDOS  is  1,  which  is  reasonable  because  InDOS  must  have  been  incremented 
when  Interrupt  21H  Function  OlH  started  to  execute. 

The  interrupt  service  routines  for  ROM  BIOS  Interrupts  05H,  lOH,  and  13H  do  nothing 
more  than  increment  and  decrement  flags  that  indicate  whether  these  interrupts  are  being 
processed  by  ROM  BIOS  routines.  These  flags  are  inspected  by  the  TSR’s  Interrupt  OSH 
and  28H  handlers. 

Executing  the  RAM-resident  application 

When  the  RAM-resident  application  is  first  activated,  it  runs  in  the  context  of  the  program 
that  was  interrupted;  that  is,  the  contents  of  the  registers,  the  video  display  mode,  the  cur¬ 
rent  PSP,  and  the  current  DTA  all  belong  to  the  interrupted  program.  The  resident  applica¬ 
tion  is  responsible  for  preserving  the  registers  and  updating  MS-DOS  with  its  PSP  and  DTA 
values. 

The  RAM-resident  application  preserves  the  previous  contents  of  the  CPU  registers  on 
its  own  stack  to  avoid  overflowing  the  interrupted  program's  stack.  It  then  installs  its  own 
handlers  for  Control-Break  (Interrupt  IBH),  Control-C  (Interrupt  23H),  and  critical  error 
(Interrupt  24H).  (Otherwise,  the  interrupted  program’s  handlers  would  take  control  if  the 
user  pressed  Ctrl-Break  or  Ctrl-C  or  if  an  MS-DOS  critical  error  occurred.)  These  handlers 
perform  no  action  other  than  setting  flags  that  can  be  inspected  later  by  the  RAM-resident 
application,  which  could  then  take  appropriate  action. 

The  application  uses  Interrupt  21H  Functions  50H  and  51H  to  update  MS-DOS  with  the 
address  of  its  PSP.  If  the  application  is  running  under  MS-DOS  versions  2.x,  the  critical 
error  flag  is  set  before  Functions  50H  and  51H  are  executed  so  that  AuxStack  is  used  for 
the  call  instead  of  lOStack,  to  avoid  corrupting  lOStack  in  the  event  that  InDOS  is  1. 

The  application  preserves  the  current  extended  error  information  with  a  call  to  Interrupt 
21H  Function  59H.  Otherwise,  the  RAM-resident  application  might  be  activated  immedi¬ 
ately  after  a  critical  error  occurred  in  the  interrupted  program  but  before  the  interrupted 
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program  had  executed  Function  59H  and,  if  a  critical  error  occurred  in  the  TSR  applica¬ 
tion,  the  interrupted  program’s  extended  error  information  would  inadvertently  be 
destroyed. 

This  example  also  shows  how  to  update  the  MS-DOS  default  DTA  using  Interrupt  21H 
Functions  lAH  and  2FH,  although  in  this  case  this  step  is  not  necessary  because  the  DTA 
is  never  used  within  the  application.  In  practice,  the  DTA  should  be  updated  only  if  the 
RAM-resident  application  includes  calls  to  Interrupt  21H  functions  that  use  a  DTA 
(Functions  IIH,  12H,  14H,  15H,  21H,  22H,  27H,  28H,  4EH,  and  4FH). 

After  the  resident  interrupt  handlers  are  installed  and  the  PSP,  DTA,  and  extended  error 
information  have  been  set  up,  the  RAM-resident  application  can  safely  execute  any  Inter¬ 
rupt  21H  function  calls  except  those  that  use  lOStack  (Functions  OlH  through  OCH).  These 
functions  cannot  be  used  within  a  RAM-resident  application  even  if  the  application  sets 
the  critical  error  flag  to  force  the  use  of  the  auxiliary  stack,  because  they  also  use  other 
non-reentrant  data  structures  such  as  input/output  buffers.  Thus,  a  RAM-resident  utility 
must  rely  either  on  user-written  console  input/output  functions  or,  as  in  the  example,  on 
ROM  BIOS  functions. 

The  application  terminates  by  returning  the  interrupted  program’s  extended  error  infor¬ 
mation,  DTA,  and  PSP  to  MS-DOS,  restoring  the  previous  Interrupt  IBH,  23H,  and  24H 
handlers,  and  restoring  the  previous  CPU  registers  and  stack. 


Richard  Wilton 
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Article  12 

Exception  Handlers 


Exceptions  are  system  events  directly  related  to  the  execution  of  an  application  program; 
they  ordinarily  cause  the  operating  system  to  abort  the  program.  Exceptions  are  thus  dif¬ 
ferent  from  errors,  which  are  minor  unexpected  events  (such  as  failure  to  find  a  file  on 
disk)  that  the  program  can  be  expected  to  handle  appropriately.  Likewise,  they  differ  from 
external  hardware  interrupts,  which  are  triggered  by  events  (such  as  a  character  arriving  at 
the  serial  port)  that  are  not  directly  related  to  the  program’s  execution. 

The  computer  hardware  assists  MS-DOS  in  the  detection  of  some  exceptions,  such  as  an 
attempt  to  divide  by  zero,  by  generating  an  internal  hardware  interrupt.  Exceptions  related 
to  peripheral  devices,  such  as  an  attempt  to  read  from  a  disk  drive  that  is  not  ready  or  does 
not  exist,  are  called  critical  errors.  Instead  of  causing  a  hardware  interrupt,  these  excep¬ 
tions  are  typically  reported  to  the  operating  system  by  device  drivers.  MS-DOS  also  sup¬ 
ports  a  third  type  of  exception,  which  is  triggered  by  the  entry  of  a  Control-C  or  Control- 
Break  at  the  keyboard  and  allows  the  user  to  signal  that  the  current  program  should  be 
terminated  immediately. 

MS-DOS  contains  built-in  handlers  for  each  type  of  exception  and  so  guarantees  a 
minimum  level  of  system  stability  that  requires  no  effort  on  the  part  of  the  application 
programmer.  For  some  applications,  however,  these  default  handlers  are  inadequate.  For 
example,  if  a  communications  program  that  controls  the  serial  port  directly  with  custom 
interrupt  handlers  is  terminated  by  the  operating  system  without  being  given  a  chance  to 
turn  off  serial-port  interrupts,  the  next  character  that  arrives  on  the  serial  line  will  trigger 
an  interrupt  for  which  a  handler  is  no  longer  present  in  memory.  The  result  will  be  a  sys¬ 
tem  crash.  Accordingly,  MS-DOS  allows  application  programs  to  install  custom  exception 
handlers  so  that  they  can  shut  down  operations  in  an  orderly  way  when  an  exception 
occurs. 

This  article  examines  the  default  exception  handlers  provided  by  MS-DOS  and  discusses 
methods  programmers  can  use  to  replace  those  routines  with  handlers  that  are  more 
closely  matched  to  specific  application  requirements. 


Overview 

Two  major  exception  handlers  of  importance  to  application  programmers  are  supported 
under  all  versions  of  MS-DOS.  The  first,  the  Control-C  exception  handler,  terminates  the 
program  and  is  invoked  when  the  user  enters  a  Ctrl-C  or  Ctrl-Break  keystroke;  the  address 
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of  this  handler  is  found  in  the  vector  for  Interrupt  23H.  The  second,  the  critical  error 
exception  handler,  is  invoked  if  MS-DOS  detects  a  critical  error  while  servicing  an  I/O 
request.  (A  critical  error  is  a  hardware  error  that  makes  normal  completion  of  the  request 
impossible.)  This  exception  handler  displays  the  familiar  Abort,  Retry,  Ignore  prompt; 
its  address  is  saved  in  the  vector  for  Interrupt  24H. 

When  a  program  begins  executing,  the  addresses  in  the  Interrupt  23H  and  24H  vectors 
usually  point  to  the  system’s  default  Control-C  and  critical  error  handlers.  If  the  program  is 
a  child  process,  however,  the  vectors  might  point  to  exception  handlers  that  belong  to  the 
parent  process,  if  the  immediate  parent  is  not  COMMAND.COM.  In  any  case,  the  applica¬ 
tion  program  can  install  its  own  custom  handler  for  Control-C  or  critical  error  exceptions 
simply  by  changing  the  address  in  the  vector  for  Interrupt  23H  or  Interrupt  24H  so  that  the 
vector  points  to  the  application’s  own  routine.  When  the  program  performs  a  final  exit  by 
means  of  Interrupt  21H  Function  OOH  (Terminate  Process),  Function  31H  (Terminate  and 
Stay  Resident),  Function  4CH  (Terminate  Process  with  Return  Code),  Interrupt  20H  (Ter¬ 
minate  Process),  or  Interrupt  27H  (Terminate  and  Stay  Resident),  MS-DOS  restores  the  pre¬ 
vious  contents  of  the  Interrupt  23H  and  24H  vectors. 

Note  that  Interrupts  23H  and  24H  never  occur  as  externally  generated  hardware  interrupts 
in  an  MS-DOS  system.  The  vectors  for  these  interrupts  are  used  simply  as  storage  areas  for 
the  addresses  of  the  exception  handlers. 

MS-DOS  also  contains  default  handlers  for  the  Control-Break  event  detected  by  the  ROM 
BIOS  in  IBM  PCs  and  compatible  computers  and  for  some  of  the  Intel  microprocessor  ex¬ 
ceptions  that  generate  actual  hardware  interrupts.  These  exception  handlers  are  not  re¬ 
placed  by  application  programs  as  often  as  the  Control-C  and  critical  error  handlers.  The 
interrupt  vectors  that  contain  the  addresses  of  these  handlers  are  not  restored  by  MS-DOS 
when  a  program  exits. 

The  address  of  the  Control-Break  handler  is  saved  in  the  vector  for  Interrupt  IBH  and  is 
invoked  by  the  ROM  BIOS  whenever  the  Ctrl-Break  key  combination  is  detected.  The 
default  MS-DOS  handler  normally  flushes  the  keyboard  input  buffer  and  substitutes 
Control-C  for  Control-Break,  and  the  Control-C  is  later  handled  by  the  Control-C  exception 
handler.  The  default  handlers  for  exceptions  that  generate  hardware  interrupts  either  abort 
the  current  program  (as  happens  with  Divide  by  Zero)  or  bring  the  entire  system  to  a  halt 
(as  for  a  memory  parity  error). 


The  Control-C  Handler 

The  vector  for  Interrupt  23H  points  to  code  that  is  executed  whenever  MS-DOS  detects  a 
Control-C  character  in  the  keyboard  input  buffer.  When  the  character  is  detected,  MS-DOS 
executes  a  software  Interrupt  23H. 

In  response  to  Interrupt  23H,  the  default  Control-C  exception  handler  aborts  the  current 
process.  Files  that  were  opened  with  handles  are  closed  (FCB-based  files  are  not),  but  no 
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Other  cleanup  is  performed.  Thus,  unsaved  data  can  be  left  in  buffers,  some  files  might 
not  be  processed,  and  critical  addresses,  such  as  the  vectors  for  custom  interrupt  handlers, 
might  be  left  pointing  into  free  RAM.  If  more  complete  control  over  process  termination  is 
wanted,  the  application  should  replace  the  default  Control-C  handler  with  custom  code. 

See  Customizing  Control-C  Handling  below. 

The  Control-Break  exception  handler,  pointed  to  by  the  vector  for  Interrupt  IBH,  is  closely 
related  to  the  Control-C  exception  handler  in  MS-DOS  systems  on  the  IBM  PC  and  close 
compatibles  but  is  called  by  the  ROM  BIOS  keyboard  driver  on  detection  of  the  Ctrl-Break 
keystroke  combination.  Because  the  Control-Break  exception  is  generated  by  the  ROM 
BIOS,  it  is  present  only  on  IBM  PC-compatible  machines  and  is  not  a  standard  feature  of 
MS-DOS.  The  default  ROM  BIOS  handler  for  Control-Break  is  a  simple  interrupt  return — 
in  other  words,  no  action  is  taken  to  handle  the  keystroke  itself,  other  than  converting  the 
Ctrl-Break  scan  code  to  an  extended  character  and  passing  it  through  to  MS-DOS  as  normal 
keyboard  input. 

To  account  for  as  many  hardware  configurations  as  possible,  MS-DOS  redirects  the  ROM 
BIOS  Control-Break  interrupt  vector  to  its  own  Control-Break  handler  during  system 
initialization.  The  MS-DOS  Control-Break  handler  sets  an  internal  flag  that  causes  the 
Ctrl-Break  keystroke  to  be  interpreted  as  a  Ctrl-C  keystroke  and  thus  causes  Interrupt  23H 
to  occur. 

Customizing  Control-C  handling 

The  exception  handlers  most  often  neglected  by  application  programmers — and  most 
often  responsible  for  major  program  failures — are  the  default  exception  handlers  invoked 
by  the  Ctrl-C  and  Ctrl-Break  keystrokes.  Although  the  user  must  be  able  to  recover  from  a 
runaway  condition  (the  reason  for  Ctrl-C  capability  in  the  first  place),  any  exit  from  a  com¬ 
plex  program  must  also  be  orderly,  with  file  buffers  flushed  to  disk,  directories  and  in¬ 
dexes  updated,  and  so  on.  The  default  Control-C  and  Control-Break  handlers  do  not 
provide  for  such  an  orderly  exit. 

The  simplest  and  most  direct  way  to  deal  with  Ctrl-C  and  Ctrl-Break  keystrokes  is  to  install 
new  exception  handlers  that  do  nothing  more  than  an  IRET  and  thus  take  MS-DOS  out  of 
the  processing  loop  entirely.  This  move  is  not  as  drastic  as  it  sounds:  It  allows  an  applica¬ 
tion  to  check  for  and  handle  the  Ctrl-C  and  Ctrl-Break  keystrokes  at  its  convenience  when 
they  arrive  through  the  normal  keyboard  input  functions  and  prevents  MS-DOS  from 
terminating  the  program  unexpectedly. 

The  following  example  sets  the  Interrupt  23H  and  Interrupt  IBH  vectors  to  point  to  an 
IRET  instruction.  When  the  user  presses  Ctrl-C  or  Ctrl-Break,  the  keystroke  combination 
is  placed  into  the  keyboard  buffer  like  any  other  keystroke.  When  it  detects  the  Ctrl-C  or 
Ctrl-Break  keystroke,  the  executing  program  should  exit  properly  (if  that  is  the  desired 
action)  after  an  appropriate  shutdown  procedure. 

To  install  the  new  exception  handlers,  the  following  procedure  iset^int)  should  be  called 
while  the  main  program  is  initializing: 
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—DATA  segment 

para  public  'DATA' 

oldintib  dd 

0 

; 

original  INT  IBH  vector 

oldint23  dd 

0 

i 

original  INT  23H  vector 

—DATA  ends 

—TEXT  segment 

byte  public  'CODE' 

assume 

cs : -TEXT, ds : -DATA, es : NOTHING 

myintib: 

f 

handler  for  Ctrl-Break 

myint23 : 

; 

handler  for  Ctrl-C 

iret 

set— int  proc 

near 

mov 

ax,351bh 

; 

get  current  contents  of 

int 

21h 

; 

Int  IBH  vector  and  save  : 

mov 

word  ptr 

oldinti b( 

rbx 

mov 

word  ptr 

oldint1b+2, es 

mov 

ax, 3523h 

; 

get  current  contents  of 

int 

21h 

; 

Int  23H  vector  and  save  : 

mov 

word  ptr 

oldint23( 

rbx 

mov 

word  ptr 

oldint23+2,es 

push 

ds 

; 

save  our  data  segment 

push 

cs 

f 

let  DS  point  to  our 

pop 

ds 

; 

code  segment 

mov 

dx, offset 

.  myintib 

mov 

ax, 251bh 

; 

set  interrupt  vector  IBH 

int 

21h 

; 

to  point  to  new  handler 

mov 

dx, offset 

,  myint23 

mov 

ax, 2523h 

; 

set  interrupt  vector  23H 

int 

21h 

; 

to  point  to  new  handler 

pop 

ds 

; 

restore  our  data  segment 

ret 

; 

back  to  caller 

set_int  endp 
-TEXT  ends 


The  application  can  use  the  following  routine  to  restore  the  original  contents  of  the  vectors 
pointing  to  the  Control-C  and  Control-Break  exception  handlers  before  making  a  final  exit 
back  to  MS-DOS.  Note  that,  although  MS-DOS  restores  the  Interrupt  23H  vector  to  its  pre¬ 
vious  contents,  the  application  must  restore  the  Interrupt  IBH  vector  itself. 


:  proc 

near 

push 

ds 

;  save  our  data  segment 

mov 

dx,word  ptr 

oldint23 

mov 

ds,word  ptr 

oldint23+2 

mov 

ax, 2523h 

;  restore  original  contents 

int 

21h 

;  of  Int  23H  vector 

pop 

ds 

/  restore  our  data  segment 

push 

ds 

;  then  save  it  again 

mov 

dx,word  ptr 

oldinti B 

mov 

ds,word  ptr 

oldinti B+2 

mov 

ax, 251 Bh 

;  restore  original  contents 

int 

21h 

;  of  Int  IBH  vector 

pop 

ret 

ds 

;  get  back  our  data  segment 
;  return  to  caller 

rest_int  endp 
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The  preceding  example  simply  prevents  MS-DOS  from  terminating  an  application  when  a 
Ctrl-C  or  Ctrl-Break  keystroke  is  detected.  Program  termination  is  still  often  the  ultimate 
goal,  but  after  a  more  orderly  shutdown  than  is  provided  by  the  MS-DOS  default  Control-C 
handler.  The  following  exception  handler  allows  the  program  to  exit  more  gracefully: 


myintib: 

;  Control-Break  exception  handler 

iret 

;  do  nothing 

myint23 : 

;  Control-C  exception  handler 

call 

safe_shut_down  ;  release  interrupt  vectors, 

;  close  files,  etc. 

jmp 

program_exit_point 

Note  that  because  the  Control-Break  handler  is  invoked  by  the  ROM  BIOS  keyboard  driver 
and  MS-DOS  is  not  reentrant,  MS-DOS  services  (such  as  closing  files  and  terminating  with 
return  code)  cannot  be  invoked  during  processing  of  a  Control-Break  exception.  In  con¬ 
trast,  any  MS-DOS  Interrupt  21H  function  call  can  be  used  during  the  processing  of  a 
Control-C  exception.  Thus,  the  Control-Break  handler  in  the  preceding  example  does 
nothing,  whereas  the  Control-C  handler  performs  orderly  shutdown  of  the  application. 

Most  often,  however,  neither  a  handler  that  does  nothing  nor  a  handler  that  shuts  down 
and  terminates  is  sufficient  for  processing  a  Ctrl-C  (or  Ctrl-Break)  keystroke.  Rather  than 
simply  prevent  Control-C  processing,  software  developers  usually  prefer  to  have  a  Ctrl-C 
keystroke  signal  some  important  action  without  terminating  the  program.  Using  methods 
similar  to  those  above,  the  programmer  can  replace  Interrupts  IBH  and  23H  with  a  routine 
like  the  following: 

myintib:  ;  Control-Break  exception  handler 

myint23:  ;  Control-C  exception  handler 

call  control_cJiappened 
iret 

Notes  on  processing  Control-C 

The  preceding  examples  assume  the  programmer  wants  to  treat  Control-C  and  Control- 
Break  the  same  way,  but  this  is  not  always  desirable.  Control-C  and  Control-Break  are  not 
the  same,  and  the  difference  between  the  two  should  be  kept  in  mind:  The  Control-Break 
handler  is  invoked  by  a  keyboard-input  interrupt  and  can  be  called  at  any  time;  the 
Control-C  handler  is  called  only  at  “safe”  points  during  the  processing  of  MS-DOS  Interrupt 
21H  functions.  Also,  even  though  MS-DOS  restores  the  Interrupt  23H  vector  on  exit  from  a 
program,  the  application  must  restore  the  previous  contents  of  the  Interrupt  IBH  vector 
before  exiting.  If  this  interrupt  vector  is  not  restored,  the  next  Ctrl-Break  keystroke  will 
cause  the  machine  to  attempt  to  execute  an  undetermined  piece  of  code  or  data  and  will 
probably  crash  the  system. 

Although  it  is  generally  desirable  to  take  control  of  the  Control-C  and  Control-Break  inter¬ 
rupts,  control  should  be  retained  only  as  long  as  necessary.  For  example,  a  RAM-resident 
pop-up  application  should  take  over  Control-C  and  Control-Break  handling  only  when  it  is 
activated,  and  it  should  restore  the  previous  contents  of  the  Interrupt  IBH  and  Interrupt 
23H  vectors  before  it  returns  control  to  the  foreground  process. 
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The  Critical  Error  Handler 

When  MS-DOS  detects  a  critical  error — an  error  that  prevents  successful  completion  of 
an  I/O  operation — it  calls  the  exception  handler  whose  address  is  stored  in  the  vector  for 
Interrupt  24H.  Information  about  the  operation  in  progress  and  the  nature  of  the  error  is 
passed  to  the  exception  handler  in  the  CPU  registers.  In  addition,  the  contents  of  all  the 
registers  at  the  point  of  the  original  MS-DOS  call  are  pushed  onto  the  stack  for  inspection 
by  the  exception  handler. 

The  action  of  MS-DOS’s  default  critical  error  handler  is  to  present  a  message  such  as 

Error  type  error  action  device 
Abort,  Retry,  Ignore? 

This  message  signals  a  hardware  error  from  which  MS-DOS  cannot  recover  without  user 
intervention.  For  example,  if  the  user  enters  the  command 

ODIR  A:  <Enter> 

but  drive  A  either  does  not  contain  a  disk  or  the  disk  drive  door  is  open,  the  MS-DOS  criti¬ 
cal  error  handler  displays  the  message 

Not  ready  error  reading  drive  A 
Abort,  Retry,  Ignore? 

/  Qgnor^  simply  tells  MS-DOS  to  forget  that  an  error  occurred  and  continue  on  its  way. 
(Of  course,  if  the  error  occurred  during  the  writing  of  a  file  to  disk,  the  file  is  generally 
corrupted;  if  the  error  occurred  during  reading,  the  data  might  be  incorrect.) 

R  (Retry)  gives  the  application  a  second  chance  to  access  the  device.  The  critical  error 
handler  returns  information  to  MS-DOS  that  says,  in  effect,  “Try  again;  maybe  it  will  work 
this  time.”  Sometimes,  the  attempt  succeeds  (as  when  the  user  closes  an  open  drive  door), 
but  more  often  the  same  or  another  critical  error  occurs. 

A  (Abort)  is  the  problem  child  of  Interrupt  24H.  If  the  user  responds  with  A,  the  applica¬ 
tion  is  terminated  immediately.  The  directory  structure  is  not  updated  for  open  files, 
interrupt  vectors  are  left  pointing  to  inappropriate  locations,  and  so  on.  In  many  cases,  re¬ 
starting  the  system  is  the  only  safe  thing  to  do  at  this  point. 

Note:  Beginning  with  version  3.3,  an  F  (Fail)  option  appears  in  the  message  displayed  by 
MS-DOS’s  default  critical  error  handler.  When  Fail  is  selected,  the  current  MS-DOS  func¬ 
tion  is  terminated  and  an  error  condition  is  returned  to  the  calling  program.  For  example, 
if  a  program  calls  Interrupt  21H  Function  3DH  to  open  a  file  on  drive  A  but  the  drive  door 
is  open,  choosing  F  in  response  to  the  error  message  causes  the  function  call  to  return 
with  the  carry  flag  set,  indicating  that  an  error  occurred  but  processing  continues. 
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Like  the  Control-C  exception  handler,  the  default  critical  error  exception  handler  can  and 
should  be  replaced  by  an  application  program  when  complete  control  of  the  system  is 
desired.  The  program  installs  its  own  handler  simply  by  placing  the  address  of  the  new 
handler  in  the  vector  for  Interrupt  24H;  MS-DOS  restores  the  previous  contents  of  the  Inter¬ 
rupt  24H  vector  when  the  program  terminates. 

Unlike  the  Control-C  handler,  however,  the  critical  error  handler  must  be  kept  within 
carefully  defined  limits  to  preserve  the  stability  of  the  operating  system.  Programmers 
must  rigidly  adhere  to  the  structure  described  in  the  following  pages  for  passing  informa¬ 
tion  to  and  from  an  Interrupt  24H  handler. 


Flags 

CS 

IP 

ES 

DS 

BP 

DI 

SI 

DX 

CX 

BX 

AX 

Hags 

CS 

IP 

T 


Flags  and  CS:IP  pushed  on  stack 
by  original  Interrupt  21H  call 


SP  on  entry  to  Interrupt  21H  handler 


Registers  at  point  of 
original  Interrupt  21H  call 


Return  address  from 
Interrupt  24H  handler 


SP  on  entry  to  Interrupt  24H  handler 


Figure  12-1.  The  stack  contents  at  entry  to  a  critical  error  exception  handler. 
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Mechanics  of  critical  error  handling 

MS-DOS  critical  error  handling  has  two  components:  the  exception  handler,  whose  ad¬ 
dress  is  saved  in  the  Interrupt  24H  vector  and  which  can  be  replaced  by  an  application 
program;  and  an  internal  routine  inside  MS-DOS.  The  internal  routine  sets  up  the  informa¬ 
tion  to  be  passed  to  the  exception  handler  on  the  stack  and  in  registers  and,  in  turn,  calls 
the  exception  handler  itself.  The  internal  routine  also  responds  to  the  values  returned  by 
the  critical  error  handler  when  that  handler  executes  an  IRET  to  return  to  the  MS-DOS 
kernel. 

Before  calling  the  exception  handler,  MS-DOS  arranges  the  stack  (Figure  12-1  on  the  pre¬ 
ceding  page)  so  the  handler  can  inspect  the  location  of  the  error  and  register  contents  at 
the  point  in  the  original  MS-DOS  function  call  that  led  to  the  critical  error. 

When  the  critical  error  handler  is  called  by  the  internal  routine,  four  registers  may  contain 
important  information:  AX,  DI,  BP,  and  SI.  (With  MS-DOS  versions  1.x,  only  the  AX  and  DI 
registers  contain  significant  information.)  The  information  passed  to  the  handler  in  the 
registers  differs  somewhat,  depending  on  whether  a  character  device  or  a  block  device  is 
causing  the  error. 

Block-device  (disk-based)  errors 

If  the  critical  error  handler  is  entered  in  response  to  a  block-device  (disk-based)  error, 
registers  BP:SI  contain  the  segment:offset  of  the  device  driver  header  for  the  device  caus¬ 
ing  the  error  and  bit  7  (the  high-order  bit)  of  the  AH  register  is  zero.  The  remaining  bits  of 
the  AH  register  contain  the  following  information  (bits  3  through  5  apply  only  to  MS-DOS 
versions  3.1  and  later): 


Bit 

Value 

Meaning 

0 

0 

Read  operation 

1 

Write  operation 

1-2 

Indicate  the  affected  disk  area: 

00 

MS-DOS 

01 

File  allocation  table 

10 

Root  directory 

11 

Files  area 

3 

0 

Fail  response  not  allowed 

1 

Fail  response  allowed 

4 

0 

Retry  response  not  allowed 

1 

Retry  response  allowed 

5 

0 

Ignore  response  not  allowed 

1 

Ignore  response  allowed 

6 

0 

Undefined 

The  AL  register  contains  the  designation  of  the  drive  where  the  error  occurred;  for  exam¬ 
ple,  AL  =  OOH  (drive  A),  AL  =  OlH  (drive  B),  and  so  on. 
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The  lower  half  of  the  DI  register  contains  the  following  error  codes  (the  upper  half  of  this 
register  is  undefined): 


Error  Code  Meaning 

OOH  Write-protected  disk 

OlH  Unknown  unit 

02H  Drive  not  ready 

03H  Invalid  command 

04H  Data  error  (CRC) 

05H  Length  of  request  structure  invalid 

06H  Seek  error 

07H  Non-MS-DOS  disk 

OSH  Sector  not  found 

09H  Printer  out  of  paper 

OAH  Write  fault 

OBH  Read  fault 

OCH  General  failure 

OFH  Invalid  disk  change  (version  3.0  or  later) 

Note:  With  versions  1.x,  the  only  valid  error  codes  are  OOH,  02H,  04H,  06H,  OSH,  OAH, 
and  OCH. 

Before  calling  the  critical  error  handler  for  a  disk-based  error,  MS-DOS  tries  from  one  to 
five  times  to  perform  the  requested  read  or  write  operation,  depending  on  the  type  of 
operation.  Critical  disk  errors  result  only  from  Interrupt  21H  operations,  not  from  failed 
sector-read  and  sector-write  operations  attempted  with  Interrupts  25H  and  26H. 

Character-device  errors 

If  the  critical  error  handler  is  called  from  the  MS-DOS  kernel  with  bit  7  of  the  AH  register 
set  to  1,  either  an  error  occurred  on  a  character  device  or  the  memory  image  of  the  file  allo¬ 
cation  table  is  bad  (a  rare  occurrence).  Again,  registers  BP:SI  contain  the  segment  and 
offset  of  the  device  driver  header  for  the  device  causing  the  critical  error.  The  exception 
handler  can  inspect  bit  15  of  the  device  attribute  word  at  offset  04H  in  the  device  header  to 
confirm  that  the  error  was  caused  by  a  character  device — this  bit  is  0  for  block  devices 
and  1  for  character  devices.  See  also  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT: 
Customizing  ms-dos:  Installable  Device  Drivers. 

If  the  error  was  caused  by  a  character  device,  the  lower  half  of  the  DI  register  contains 
error  codes  as  described  above  and  the  contents  of  the  AL  register  are  undefined.  The 
exception  handler  can  inspect  the  other  fields  of  the  device  header  to  obtain  the  logical 
name  of  the  character  device;  to  determine  whether  that  device  is  the  standard  input, 
standard  output,  or  both;  and  so  on. 

Critical  error  processing 

The  critical  error  exception  handler  is  entered  from  MS-DOS  with  interrupts  disabled. 
Because  an  MS-DOS  system  call  is  already  in  progress  and  MS-DOS  is  not  reentrant,  the 
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handler  cannot  request  any  MS-DOS  system  services  other  than  Interrupt  21H  Functions 
01  through  OCH  (ctoracter  I/O  functions),  Interrupt  21H  Function  30H  (Get  MS-DOS  Version 
Number),  and  Interrupt  21H  Function  59H  (Get  Extended  Error  Information).  These  func¬ 
tions  use  a  special  stack  so  that  they  can  be  called  during  error  processing. 

In  general,  the  critical  error  handler  must  preserve  all  but  the  AL  register.  It  must  not 
change  the  contents  of  the  device  header  pointed  to  by  BP:SI.  The  handler  must  return  to 
the  MS-DOS  kernel  with  an  IRET,  passing  an  action  code  in  register  AL  as  follows: 


Value  in  AL  Meaning 

OOH  Ignore 

OlH  Retry 

02H  Terminate  process 

03H  Fail  current  system  call 

These  values  correspond  to  the  options  presented  by  the  MS-DOS  default  critical  error 
handler.  The  default  handler  prompts  the  user  for  input,  places  the  appropriate  return 
information  in  the  AL  register,  and  immediately  issues  an  IRET  instruction. 

Note:  Although  the  Fail  option  is  displayed  by  the  MS-DOS  default  critical  error  handler 
in  versions  3.3  and  later,  the  Fail  option  inside  the  handler  was  added  in  version  3.1. 

With  MS-DOS  versions  3.1  and  later,  if  the  handler  returns  an  action  code  in  AL  that  is  not 
allowed  for  the  error  in  question  (bits  3  through  5  of  the  AH  register  at  the  point  of  call), 
MS-DOS  reacts  according  to  the  following  rules: 

If  Ignore  is  specified  by  AL  =  OOH  but  is  not  allowed  because  bit  5  of  AH  =  0,  the  response 
defaults  to  Fail  (AL  =  03H). 

If  Retry  is  specified  by  AL  =  OlH  but  is  not  allowed  because  bit  4  of  AH  =  0,  the  response 
defaults  to  Fail  (AL  =  03H). 

If  Fail  is  specified  by  AL  =  03H  but  is  not  allowed  because  bit  3  of  AH  =  0,  the  response 
defaults  to  Abort. 

Custom  critical  error  handlers 

Each  time  it  receives  control,  COMMAND.COM  restores  the  Interrupt  24H  vector  to  point 
to  the  system’s  default  critical  error  handler  and  displays  a  prompt  to  the  user.  Conse¬ 
quently,  a  single  custom  handler  cannot  terminate  and  stay  resident  to  provide  critical 
error  handling  services  for  subsequent  application  programs.  Each  program  that  needs 
better  critical  error  handling  than  MS-DOS  provides  must  contain  its  own  critical  error 
handler. 

Figure  12-2  contains  a  simple  critical  error  handler,  INT24.ASM,  written  in  assembly  lan¬ 
guage.  In  the  form  shown,  INT24.ASM  is  no  more  than  a  functional  replacement  for  the 
MS-DOS  default  critical  error  handler,  but  it  can  be  used  as  the  basis  for  more  sophisticated 
handlers  that  can  be  incorporated  into  application  programs. 
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INT24.ASM  contains  three  routines: 


Routine  Action 

get24  Saves  the  previous  contents  of  the  Interrupt  24H  critical  error  handler  vec¬ 

tor  and  stores  the  address  of  the  new  critical  error  handler  into  the  vector. 
res24  Restores  the  address  of  the  previous  critical  error  handler,  which  was 

saved  by  a  call  to  get24y  into  the  Interrupt  24  vector. 
int24  Replaces  the  MS-DOS  critical  error  handler. 

A  program  wishing  to  substitute  the  new  critical  error  handler  for  the  system’s  default  han¬ 
dler  should  call  the  get24  routine  during  its  initialization  sequence.  If  the  program  wishes 
to  revert  to  the  system’s  default  handler  during  execution,  it  can  accomplish  this  with  a  call 
to  the  res24  routine.  Otherwise,  a  call  to  res24  (and  the  presence  of  the  routine  itself  in 
the  program)  is  not  necessary,  because  MS-DOS  automatically  restores  the  Interrupt  24H 
vector  to  its  previous  value  when  the  program  exits,  from  information 
stored  in  the  program  segment  prefix  (PSP). 

The  replacement  critical  error  handler,  int24,  is  simple.  First  it  saves  all  registers;  then  it 
displays  a  message  that  a  critical  error  has  occurred  and  prompts  the  user  to  enter  a  key 
selecting  one  of  the  four  possible  options:  Abort,  Retry,  Ignore,  or  Fail  If  an  illegal  key  is 
entered,  the  prompt  is  displayed  again;  otherwise,  the  action  code  corresponding  to  the 
key  is  extracted  from  a  table  and  placed  in  the  AL  register,  the  other  registers  are  restored, 
and  control  is  returned  to  the  MS-DOS  kernel  with  an  IRET  instruction. 

Note  that  the  handle  read  and  write  functions  (Interrupt  21H  Functions  3FH  and  40H), 
which  would  normally  be  preferred  for  interaction  with  the  display  and  keyboard,  cannot 
be  used  in  a  critical  error  handler. 

name  int24 

title  INT24  Critical  Error  Handler 


;  INT24.ASM  —  Replacement  critical  error  handler 
;  by  Ray  Duncan,  September  1987 


cr 

equ 

Odh 

;  ASCII  carriage  return 

If 

equ 

Oah 

;  ASCII  linefeed 

DGROUP 

group 

-DATA 

-DATA 

segment 

word  public 

' DATA ' 

save24 

dd 

0 

;  previous  contents  of  Int 

;  critical  error  handler  vector 

Figure  12-2.  INT24.  ASM,  a  replacement  Interrupt  24H  handler.  (more ) 
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;  prompt  message  used  by 
;  critical  error  handler 

prompt  db  cr, If Critical  Error  Occurred:  ' 

db  'Abort,  Retry,  Ignore,  Fail?  $' 


keys  db  'aArRilfF' 

keys_len  equ  $-keys 

codes  db  2, 2, 1 , 1 , 0, 0, 3, 3 

_X)ATA  ends 


;  possible  user  response  keys 
;  (both  cases  of  each  allowed) 

;  codes  returned  to  MS-DOS  kernel 
;  for  corresponding  response  keys 


—TEXT  segment  word  public  'CODE' 
assume  cs :_TEXT, ds : DGROUP 


public  get24 
get24  proc  near 


;  set  Int  24H  vector  to  point 
;  to  new  critical  error  handler 


push  ds  ;  save  segment  registers 

push  es 


mov  ax,3524h 

int  21 h 


;  get  address  of  previous 
;  INT  24H  handler  and  save  it 


mov  word  ptr  save24,bx 

mov  word  ptr  save24+2,es 


push  cs  ;  set  DS:DX  to  point  to 

pop  ds  ;  new  INT  24H  handler 

mov  dx, offset  _TEXT:int24 


mov  ax,2524h 

int  21  h 

pop  es 

pop  ds 

ret 

get 2 4  endp 

public  res24 

res24  proc  near 

push  ds 

Figure  12-2.  Continued. 


;  then  call  MS-DOS  to 
;  set  the  INT  24H  vector 

;  restore  segment  registers 

;  and  return  to  caller 

;  restore  original  contents 
;  of  Int  24H  vector 

;  save  our  data  segment 


(more) 
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Ids 

mov 

int 

dx, save24 
ax,2524h 

21h 

;  put  address  of  old  handler 
;  back  into  INT  24H  vector 

pop 

ret 

ds 

;  restore  data  segment 
;  and  return  to  caller 

endp 

;  This  is  the  replacement  critical  error  handler.  It 
;  prompts  the  user  for  Abort,  Retry,  Ignore,  or  Fail  and 
;  returns  the  appropriate  code  to  the  MS-DOS  kernel. 


int24 


int24a: 


proc 

far 

entered  from  MS-DOS  kernel 

push 

bx 

; 

save  registers 

push 

cx 

push 

dx 

push 

si 

push 

di 

push 

bp 

push 

ds 

push 

es 

mov 

ax,DGROUP 

/ 

display  prompt  for  user 

mov 

ds,  ax 

0 

using  function  09H  (print  string 

mov 

es,  ax 

0 

terminated  by  $  character) 

mov 

dx, offset 

prompt 

mov 

ah,09h 

int 

21h 

mov 

ah,01h 

; 

get  user's  response 

int 

21h 

function  01 H  =  read  one  character 

mov 

di, of fset 

keys  ; 

look  up  code  for  response  key 

mov 

cx, keys_len 

cld 

repne 

scasb 

jnz 

int24a 

; 

prompt  again  if  bad  response 

;  set  AL  =  action  code  for  MS-DOS 
;  according  to  key  that  was  entered: 

;  0  =  ignore,  1  =  retry,  2  =  abort,  3  =  fail 
mov  al, [di+keys_len-1 ] 


pop  es 

pop  ds 

pop  bp 

pop  di 

pop  si 

Figure  12-2.  Continued. 


;  restore  registers 


(more) 
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pop  dx 

pop  cx 

pop  bx 

iret  ;  exit  critical  error  handler 

int24  endp 
-TEXT  ends 
end 

Figure  12-2.  Continued. 


Hardware-generated  Exception  Interrupts 

Intel  reserved  the  vectors  for  Interrupts  OOH  through  IFH  (Table  12-1)  for  exceptions 
generated  by  the  execution  of  various  machine  instructions.  Handling  of  these  chip- 
dependent  internal  interrupts  can  vary  from  one  make  of  MS-DOS  machine  to  another; 
some  such  differences  are  mentioned  in  the  discussion. 

Table  12-1.  Intel  Reserved  Exception  Interrupts. 


Interrupt 

Number  Definition 


OOH 

Divide  by  Zero 

OlH 

Single-Step 

02H 

Nonmaskable  Interrupt  (NMI) 

03H 

Breakpoint  Trap 

04H 

Overflow  Trap 

05H 

BOUND  Range  Exceeded* 

06H 

Invalid  Opcode* 

07H 

Coprocessor  not  Available! 

OSH 

Double-Fault  Exception! 

09H 

Coprocessor  Segment  Overrun! 

OAH 

Invalid  Task  State  Segment  (TSS)! 

OBH 

Segment  not  Present! 

OCH 

Stack  Exception! 

ODH 

General  Protection  Exception! 

OEH 

Page  Fault! 

OFH 

(Reserved) 

lOH 

Coprocessor  Error! 

11-lFH 

(Reserved) 

*The  80186, 80286,  and  80386  microprocessors  only. 
fThe  80286  and  80386  microprocessors  only. 

:j:The  80386  microprocessor  only. 
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Note:  A  number  of  these  reserved  exception  interrupts  generally  do  not  occur  in  MS-DOS 
because  they  are  generated  only  when  the  80286  or  80386  microprocessor  is  operating  in 
protected  mode.  The  following  discussions  do  not  cover  these  interrupts. 

Divide  by  Zero  (Interrupt  OOH) 

An  Interrupt  OOH  occurs  whenever  a  DIV  or  IDI V  operation  fails  to  terminate  within  a 
reasonable  period  of  time.  The  interrupt  is  triggered  by  a  mathematical  anomaly:  Division 
by  zero  is  inherently  undefined.  To  handle  such  situations,  Intel  built  special  processing 
into  the  DIV  and  IDIV  instructions  to  ensure  that  the  condition  does  not  cause  the  pro¬ 
cessor  to  lock  up.  Although  the  assumption  underlying  Interrupt  OOH  is  an  attempt  to 
divide  by  zero  (a  condition  that  will  never  terminate),  the  interrupt  can  also  be  triggered 
by  other  error  conditions,  such  as  a  quotient  that  is  too  large  to  fit  in  the  designated  register 
(AXorAL). 

The  ROM  BIOS  handler  for  Interrupt  OOH  in  the  IBM  PC  and  close  compatibles  is  a  simple 
IRET  instruction.  During  the  MS-DOS  startup  process,  however,  MS-DOS  modifies  the  in¬ 
terrupt  vector  to  point  to  its  own  handler — a  routine  that  issues  the  warning  message 
Divide  by  Zero  and  aborts  the  current  application.  This  abort  procedure  can  leave  the 
computer  and  operating  system  in  an  extremely  unstable  state.  If  the  default  handler  is 
used,  the  system  should  be  restarted  immediately  and  an  attempt  should  be  made  to  find 
and  eliminate  the  cause  of  the  error.  A  better  approach,  however,  is  to  provide  a  replace¬ 
ment  handler  that  treats  Interrupt  OOH  much  as  MS-DOS  treats  Interrupt  24H. 

Single-Step  (Interrupt  OlH) 

If  the  trap  flag  (bit  8  of  the  microprocessor's  l6-bit  flags  register)  is  set.  Interrupt  OlH 
occurs  at  the  end  of  every  instruction  executed  by  the  processor.  By  default.  Interrupt  OlH 
points  to  a  simple  IRET  instruction,  so  the  net  effect  is  as  if  nothing  happened.  However, 
debugging  programs,  which  are  the  only  applications  that  use  this  interrupt,  modify  the 
interrupt  vector  to  point  to  their  own  handlers.  The  interrupt  can  then  be  used  to  allow  a 
debugger  to  single-step  through  the  machine  instructions  of  the  program  being  debugged, 
as  DEBUG  does  with  its  T  (Trace)  command. 

Nonmaskable  Interrupt,  or  NMI  (Interrupt  02H) 

In  the  hardware  architecture  of  IBM  PCs  and  close  compatibles.  Interrupt  02H  is  invoked 
whenever  a  memory  parity  error  is  detected.  MS-DOS  provides  no  handler,  because  this 
error,  as  a  hardware-related  problem,  is  in  the  domain  of  the  ROM  BIOS. 

In  response  to  the  Interrupt  02H,  the  default  ROM  BIOS  handler  displays  a  message  and 
locks  the  machine,  on  the  assumption  that  bad  memory  prevents  reliable  system  opera¬ 
tion.  Many  programmers,  however,  prefer  to  include  code  that  permits  orderly  shutdown 
of  the  system.  Replacing  the  ROM  BIOS  parity  trap  routine  can  be  dangerous,  though, 
because  a  parity  error  detected  in  memory  means  the  contents  of  RAM  are  no  longer  reli¬ 
able — even  the  memory  locations  containing  the  NMI  handler  itself  might  be  defective. 
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Breakpoint  Trap  (Interrupt  03H) 

Interrupt  03H,  which  is  used  in  conjunction  with  Interrupt  OlH  for  debugging,  is  invoked 
by  a  special  1-byte  opcode  (OCCH).  During  a  debugging  session,  a  debugger  modifies  the 
vector  for  Interrupt  03H  to  point  to  its  own  handler  and  then  replaces  1  byte  of  program 
opcode  with  the  OCCH  opcode  at  any  location  where  a  breakpoint  is  needed. 

When  a  breakpoint  is  reached,  the  OCCH  opcode  triggers  Interrupt  03H  and  the  debugger 
regains  control.  The  debugger  then  restores  the  original  opcode  in  the  program  being 
debugged  and  issues  a  prompt  so  that  the  user  can  display  or  alter  the  contents  of  memory 
or  registers.  The  use  of  Interrupt  03H  is  illustrated  by  DEBUG  and  SYMDEB’s  breakpoint 
capabilities. 

Overflow  Trap  (Interrupt  04H) 

If  the  overflow  bit  (bit  11)  in  the  microprocessor’s  flags  register  is  set.  Interrupt  04H  occurs 
when  the  INTO  (Interrupt  on  Overflow)  instruction  is  executed.  The  overflow  bit  can  be 
set  during  prior  execution  of  any  arithmetic  instruction  (such  as  MUL  or  IMUL)  that  can 
produce  an  overflow  error. 

The  ROM  BIOS  of  the  IBM  PC  and  close  compatibles  initializes  the  Interrupt  04H  vector  to 
point  to  an  IRET,  so  this  interrupt  becomes  invisible  to  the  user  if  it  is  executed.  MS-DOS 
does  not  have  its  own  handler  for  Interrupt  04H.  However,  because  the  Intel  microproces¬ 
sors  also  include  JO  (Jump  if  Overflow)  and  JNO  (Jump  if  No  Overflow)  instructions, 
applications  rarely  need  the  INTO  instruction  and,  hence,  seldom  have  to  provide  their 
own  Interrupt  04H  handlers. 

BOUND  Range  Exceeded  (Interrupt  05H) 

Interrupt  05H  is  generated  on  80186, 80286,  and  80386  microprocessors  if  a  BOUND 
instruction  is  executed  to  test  the  value  of  an  array  index  and  the  index  falls  outside  the 
limits  specified  by  the  instruction’s  operand.  The  exception  handler  is  expected  to  alter 
the  index  so  that  it  is  correct — when  the  handler  performs  an  interrupt  return  (IRET),  the 
CPU  reexecutes  the  BOUND  instruction  that  caused  the  interrupt. 

On  IBM  PCAT-compatible  machines,  the  ROM  BIOS  assignment  of  the  PrtSc  (print  screen) 
routine  to  Interrupt  05H  is  in  conflict  with  the  CPU’s  use  of  Interrupt  05H  for  BOUND 
exceptions. 

Invalid  opcode  (Interrupt  06H) 

Interrupt  06H  is  generated  by  the  80186, 80286,  and  80386  microprocessors  if  the  current 
instruction  is  not  a  valid  opcode — for  example,  if  the  machine  tries  to  execute  a  data 
statement. 

On  IBM  PCMTs,  Interrupt  06H  simply  points  to  an  IRET  instruction.  The  ROM  BIOS  rou¬ 
tines  of  some  IBM  PCAT-compatibles,  however,  provide  an  interrupt  handler  that  reports 
an  unexpected  software  Interrupt  06H  and  asks  if  the  user  wants  to  continue.  A  V  re¬ 
sponse  causes  the  interrupt  handler  to  skip  over  the  invalid  opcode.  Unfortunately, 
because  the  succeeding  opcode  is  often  invalid  as  well,  the  user  may  have  the  feeling  of 
being  trapped  in  a  loop. 
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Extended  Error  Information 

Under  MS-DOS  versions  1.x,  the  operating  system  provided  limited  information  about 
errors  that  occurred  during  calls  to  the  Interrupt  21H  system  functions.  For  example,  if  a 
program  called  Function  OFH  to  open  a  file,  there  were  only  two  possible  results:  On 
return,  the  AL  register  either  contained  OOH  for  a  successful  open  or  OFFH  for  failure.  No 
further  detail  was  available  from  the  operating  system.  Although  some  of  these  early  sys¬ 
tem  calls  (such  as  the  read  and  write  functions)  returned  somewhat  more  information, 
the  1.x  versions  of  MS-DOS  were  essentially  limited  to  success/failure  return  codes. 

Beginning  with  version  2.0  and  the  introduction  of  the  handle  concept,  additional  error 
information  became  available.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT: 
Programming  for  ms-dos:  File  and  Record  Management.  For  example,  if  a  program 
attempts  to  open  a  file  with  Interrupt  21H  Function  3DH  (Open  File  with  Handle),  it  can 
check  the  status  of  the  carry  flag  on  return  to  detect  whether  an  error  occurred.  If  the 
carry  flag  is  not  set,  the  call  was  successful  and  the  AX  register  contains  the  file  handle. 

If  the  carry  flag  is  set,  the  AX  register  contains  one  of  the  following  possible  error  codes: 


Error  Code 

Meaning 

OlH 

Invalid  function  code 

02H 

File  not  found 

03H 

Path  not  found 

04H 

Too  many  open  files  (no  more  handles  available) 

05H 

Access  denied 

OCH 

Invalid  access  code 

In  some  circumstances,  however,  even  these  error  codes  do  not  provide  enough  infor¬ 
mation.  Therefore,  beginning  with  version  3.0,  MS-DOS  made  extended  error  information 
available  through  Interrupt  21H  Function  59H  (Get  Extended  Error  Information).  This 
function  can  be  called  after  any  other  Interrupt  21H  function  fails,  or  it  can  be  called  from  a 
critical  error  handler.  The  extended  error  codes,  briefly  described  below,  maintain  com¬ 
patibility  with  the  MS-DOS  versions  2.x  error  returns  and  are  grouped  as  follows: 


Error  Code  Error  Group 

OOH  No  error  encountered. 

01-  12H  MS-DOS  versions  2.x  and  3.x  Interrupt  21H  errors.  These  error  codes  are 

identical  to  those  returned  in  the  AX  register  by  Functions  38H  through 
57H  if  the  carry  flag  is  set  on  return  from  the  function  call. 

13-  IFH  MS-DOS  versions  2.x  and  3.x  Interrupt  24H  errors.  These  error  codes  are 

13H  (19)  greater  than  the  codes  passed  to  a  critical  error  handler  in  the 
lower  half  of  the  DI  register;  that  is,  if  the  critical  error  handler  receives 
error  code  04H  (CRC  error),  Interrupt  21H  Function  59H  returns  17H. 

20-58H  Extended  error  codes,  many  related  to  networking  and  file  sharing,  for 

MS-DOS  versions  3.0  and  later. 
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Note:  The  contents  of  the  CPU  registers  (except  CS:IP  and  SS:SP)  are  destroyed  by  a  call 
to  Function  59H.  Also,  as  mentioned  earlier,  this  function  is  available  only  with  MS-DOS 
versions  3.x,  even  though  it  maintains  compatibility  with  error  returns  in  versions  2.x. 

On  return.  Function  59H  provides  the  extended  error  code  in  the  AX  register,  the  error 
class  (type)  in  the  BH  register,  a  code  for  the  suggested  corrective  action  in  the  BL  register, 
and  the  locus  of  the  error  in  the  CH  register.  These  values  are  defined  in  the  following 
paragraphs.  With  MS-DOS  or  PC-DOS  versions  3.x,  if  an  error  22H  (invalid  disk  change) 
occurs  and  if  the  capability  is  supported  by  the  system’s  block-device  drivers,  ES:DI  points 
to  an  ASCIIZ  volume  label  that  designates  the  disk  to  be  inserted  in  the  drive  before  the 
operation  is  retried. 

Error  Code  (AX  register).  This  value  is  defined  as  follows: 


Value  in  AX 

Meaning 

Interrupt  21H  errors  (MS-DOS  versions  2.0  and  later): 

OlH 

Invalid  function  number 

02H 

File  not  found 

03H 

Path  not  found 

04H 

Too  many  open  files  (no  handles  available) 

05H 

Access  denied 

06H 

Invalid  handle 

07H 

Memory  control  blocks  destroyed 

OSH 

Insufficient  memory 

09H 

Invalid  memory-block  address 

OAH 

Invalid  environment 

OBH 

Invalid  format 

OCH 

Invalid  access  code 

ODH 

Invalid  data 

OEH 

Reserved 

OFH 

Invalid  disk  drive  specified 

lOH 

Attempt  to  remove  the  current  directory 

IIH 

Not  same  device 

12H 

No  more  files 

Interrupt  24H  errors  (MS-DOS  versions  2.0  and  later): 

13H  Attempt  to  write  on  write-protected  disk 

14H  Unknown  unit 

1 5H  Drive  not  ready 

16H  Invalid  command 

17H  Data  error  based  on  cyclic  redundancy  check  (CRC) 

18H  Length  of  request  structure  invalid 

19H  Seek  error 


(more) 
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Value  in  AX 

Meaning 

Interrupt  24H  errors  (continued) 

lAH 

Unknown  media  type  (non-MS-DOS  disk) 

IBH 

Sector  not  found 

ICH 

Printer  out  of  paper 

lOH 

Write  fault 

lEH 

Read  fault 

IFH 

General  failure 

MS-DOS  versions  3-x  extended  errors; 

20H 

Sharing  violation 

21H 

Lock  violation 

22H 

Invalid  disk  change 

23H 

FCB  unavailable 

24H 

Sharing  buffer  exceeded 

25H-31H 

Reserved 

32H 

Network  request  not  supported 

33H 

Remote  computer  not  listening 

34H 

Duplicate  name  on  network 

35H 

Network  name  not  found 

36H 

Network  busy 

37H 

Device  no  longer  exists  on  network 

38H 

Net  BIOS  command  limit  exceeded 

39H 

Error  in  network  adapter  hardware 

3AH 

Incorrect  response  from  network 

3BH 

Unexpected  network  error 

3CH 

Incompatible  remote  adapter 

3DH 

Print  queue  full 

3EH 

Queue  not  full 

3FH 

Not  enough  room  for  print  file 

40H 

Network  name  deleted 

41H 

Access  denied 

42H 

Incorrect  network  device  type 

43H 

Network  name  not  found 

44H 

Network  name  limit  exceeded 

45H 

Net  BIOS  session  limit  exceeded 

46H 

Temporary  pause 

47H 

Network  request  not  accepted 

48H 

Print  or  disk  redirection  paused 

49H-4FH 

Reserved 

50H 

File  already  exists 

51H 

Reserved 

(more) 
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Value  in  AX  Meaning 

MS-DOS  versions  3.x  extended  errors  (continued) 


52H 

Cannot  make  directory 

53H 

Failure  on  Interrupt  24H 

54H 

Out  of  structures 

55H 

Already  assigned 

56H 

Invalid  password 

57H 

Invalid  parameter 

58H 

Network  write  fault 

Locus  (CH  register).  This  value  provides  information  on  the  location  of  the  error: 


Value  in  CH  Meaning 

OlH  Location  unknown 

02H  Block  device;  generally  caused  by  a  disk  error 

03H  Network 

04H  Serial  device;  generally  caused  by  a  timeout  from  a  character  device 

05H  Memory;  caused  by  an  error  in  RAM 

Error  Class  (BH  register).  This  value  gives  the  general  category  of  the  error: 


Value  inBH  Meaning 

OlH  Out  of  resource;  out  of  storage  space  or  I/O  channels. 

02H  Temporary  situation;  expected  to  clear,  as  in  a  file  or  record  lock — gener¬ 

ally  occurs  only  in  a  network  environment. 

03H  Authorization;  a  problem  with  permission  to  access  the  requested  device. 

04H  Internal  error  in  system  software;  generally  reflects  a  system  software  bug 

rather  than  an  application  or  system  failure. 

05H  Hardware  failure;  a  serious  hardware-related  problem  not  the  fault  of  the 

user  program. 

06H  System  failure;  a  serious  failure  of  the  system  software,  not  directly  the 

fault  of  the  application — generally  occurs  if  configuration  files  are 
missing  or  incorrect. 

07H  Application-program  error;  generally  caused  by  inconsistent  function 

requests  from  the  user  program. 

OSH  File  or  item  not  found. 

09H  File  or  item  of  invalid  format  or  type  detected,  or  an  otherwise  unsuitable 

or  invalid  item  requested. 

OAH  File  or  item  interlocked  by  the  system. 


(more) 
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Value  in  BH  Meaning 

OBH  Media  failure;  generally  occurs  with  a  bad  disk  in  a  drive,  a  bad  spot  on  the 

disk,  or  the  like. 

OCH  Already  exists;  generally  occurs  when  application  tries  to  declare  a 

machine  name  or  device  that  already  exists. 

ODH  Unknown. 

Suggested  Action  (BL  register).  One  of  the  most  useful  returns  from  Function  59H,  this 
value  suggests  a  corrective  action  to  try: 


Value  in  BL  Meaning 

OlH  Retry  a  few  times  before  prompting  the  user  to  choose  Ignore  for  the 

program  to  continue  or  Abort  to  terminate. 

02H  Pause  for  a  few  seconds  between  retries  and  then  prompt  user  as  above. 

03H  Ask  user  to  reenter  the  input.  In  most  cases,  this  solution  applies  when  an 

incorrect  drive  specifier  or  filename  was  entered.  Of  course,  if  the  value 
was  hard-coded  into  the  program,  the  user  should  not  be  prompted  for 
input. 

04H  Clean  up  as  well  as  possible,  then  abort  the  application.  This  solution 

applies  when  the  error  is  destructive  enough  that  the  application  cannot 
safely  proceed,  but  the  system  is  healthy  enough  to  try  an  orderly  shut¬ 
down  of  the  application. 

05H  Exit  from  the  application  as  soon  as  possible,  without  trying  to  close  files 

and  clean  up.  This  means  something  is  seriously  wrong  with  either  the 
application  or  the  system. 

06H  Ignore;  error  is  informational. 

07H  Prompt  user  to  perform  some  action,  such  as  changing  floppy  disks  in  a 

drive  and  then  retry. 

Function  59H  and  older  system  calls 

The  Interrupt  21H  functions — primarily  the  FCB-related  file  and  record  calls — that  return 

OFFH  in  the  AL  register  to  indicate  that  an  error  has  occurred  but  provide  no  further  infor¬ 
mation  about  the  type  of  error  include 


Function  Name 


OFH 

Open  File  with  FCB 

lOH 

Close  File  with  FCB 

IIH 

Find  First  File 

12H 

Find  Next  File 

(more) 
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Function 

Name 

13H 

Delete  File 

16H 

Create  File  with  FCB 

17H 

Rename  File 

23H 

Get  File  Size 

These  function  calls  now  exist  only  to  maintain  compatibility  with  MS-DOS  versions  1.x. 
The  preferred  choices  are  the  handle-style  calls  available  in  MS-DOS  versions  2.0  and  later, 
which  offer  full  path  support  and  much  better  error  reporting.  See  also  SYSTEM  CALLS. 

If  the  older  calls  must  be  used,  the  program  can  use  Function  59H  to  obtain  more  detailed 
information  under  MS-DOS  version  3.0  or  later.  For  example: 


myfcb 

db 

0 

;  drive  =  default 

db 

'MYFILE  * 

;  filename,  8  chars 

db 

'DAT' 

;  extension,  3  chars 

db 

25  dup  (0) 

;  remainder  of  FCB 

mov 

dx,seg  myfcb 

DS:DX  =  FCB 

mov 

ds,  dx 

mov 

dx, offset  myfcb 

mov 

ah,0fh 

function  OFH  =  Open  FCB 

int 

21h 

transfer  to  MS-DOS 

or 

al,al 

test  status 

jz 

success 

jump,  open  succeeded 
open  failed,  get 
extended  error  info 

mov 

bx,  0 

BX  =  OOH  for  ver.  2.x-3.x 

mov 

ah,59h  ; 

function  59H  =  Get  Info 

int 

21h  ; 

transfer  to  MS-DOS 

or 

ax, ax  j 

really  an  error? 

jz 

success  ; 

no  error,  jump 

test  recommended  actions 

cmp 

bl,01h 

jz 

retry  ; 

r  if  BL  =  01H  retry  operation 

cmp 

bl,04h 

jz 

cleanup  ; 

r  if  BL  =  04H  clean  up  and  exit 

cmp 

bl,05h 

jz 

panic  ; 

r  if  BL  =  OSH  exit  immediately 

Function  59H  and  newer  system  calls 

The  function  calls  listed  below  were  added  in  MS-DOS  versions  2.0  and  later.  These  calls 
return  with  the  carry  flag  set  if  an  error  occurs;  in  addition,  the  AX  register  contains  an 
error  value  corresponding  to  error  codes  OlH  through  12H  of  the  extended  error  return 
codes: 
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Function  Name 

MS-DOS  versions  2.0  and  later: 

38H  Get/Set  Current  Country 

39H  Create  Directory 

3AH  Remove  Directory 

3BH  Change  Current  Directory 

3CH  Create  File  with  Handle 

3DH  Open  File  with  Handle 

3EH  Close  File 

3FH  Read  File  or  Device 

40H  Write  File  or  Device 

41H  Delete  File 

42H  Move  File  Pointer 

43H  Get/Set  File  Attributes 

44H  lOCTL  (I/O  Control  for  Devices) 

45H  Duplicate  File  Handle 

46H  Force  Duplicate  File  Handle 

47H  Get  Current  Directory 

48H  Allocate  Memory  Block 

49H  Free  Memory  Block 

4AH  Resize  Memory  Block 

4BH  Load  and  Execute  Program  (EXEC) 

4EH  Find  First  File 

4FH  Find  Next  File 

56H  Rename  File 

57H  Get/Set  Date/Time  of  File 


MS-DOS  versions  3.0  and  later: 

58H  Get/Set  Allocation  Strategy 

5AH  Create  Temporary  File 

5BH  Create  New  File 

5CH  Lock/Unlock  File  Region 


MS-DOS  versions  3«1  and  later: 

5EH  Network  Machine  Name/Printer  Setup 

5FH  Get/Make  Assign  List  Entry 

Although  these  newer  functions  have  much  better  error  reporting  than  the  older  FCB 
functions,  Function  59H  is  still  useful.  Regardless  of  the  version  of  MS-DOS  that  is  running, 
the  error  code  returned  in  the  AX  register  from  an  Interrupt  21H  function  call  is  always  in 
the  range  0-12H.  If  a  program  is  running  under  MS-DOS  versions  3.x  and  wants  to  obtain 
one  or  more  of  the  more  specific  error  codes  in  the  range  20-58H,  the  program  must 
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follow  the  failed  Interrupt  21H  call  with  a  subsequent  call  to  Interrupt  21H  Function  59H. 
The  program  can  then  use  the  code  returned  by  Function  59H  in  the  BL  register  as  a  guide 
to  the  action  to  take  in  response  to  the  error.  For  example: 


myfile 


db  ’MYFILE.DAT' , 0 


mov  dx,seg  myfile 

mov  ds , dx 

mov  dx, offset  myfile 

mov  ax,3d02h 

int  21  h 

jnc  success 

mov  bx, 0 

mov  ah,59h 

int  21  h 

or  ax, ax 

jz  success 

cmp  bl,01h 

jz  retry 


ASCIIZ  filename 


DS:DX  =  ASCIIZ  filename 


open,  read/write 
transfer  to  MS-DOS 
jump,  open  succeeded 
open  failed,  get 
extended  error  info 
BX  =  OOH  for  ver.  2.X-3.X 
function  59H  =  Get  Info 
transfer  to  MS-DOS 
really  an  error? 
no  error,  jump 
test  recommended  actions 

if  BL  =  01H  retry  operation 


If  the  standard  critical  error  handler  is  replaced  with  a  customized  critical  handler, 
Function  59H  can  also  be  used  to  obtain  more  detailed  information  about  an  error  inside 
the  handler  before  either  returning  control  to  the  application  or  aborting.  The  value  in  the 
BL  register  should  be  used  to  determine  the  appropriate  action  to  take  or  the  message  to 
display  to  the  user. 


Jim  Kyle 
Chip  Rabinowitz 
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Hardware  Interrupt  Handlers 


Unlike  software  interrupts,  which  are  service  requests  initiated  by  a  program,  hardware 
interrupts  occur  in  response  to  electrical  signals  received  from  a  peripheral  device  such  as 
a  serial  port  or  a  disk  controller,  or  they  are  generated  internally  by  the  microprocessor 
itself.  Hardware  interrupts,  whether  external  or  internal  to  the  microprocessor,  are  given 
prioritized  servicing  by  the  Intel  CPU  architecture. 

The  8086  family  of  microprocessors  (which  includes  the  8088, 8086, 80186, 80286, 
and  80386)  reserves  the  first  1024  bytes  of  memory  (addresses  0000:0000H  through 
0000:03FFH)  for  a  table  of  256  interrupt  vectors,  each  a  4-byte  far  pointer  to  a  specific 
interrupt  service  routine  (ISR)  that  is  carried  out  when  the  corresponding  interrupt  is  pro¬ 
cessed.  The  design  of  the  8086  family  requires  certain  of  these  interrupt  vectors  to  be  used 
for  specific  functions  (Table  13-1).  Although  Intel  actually  reserves  the  first  32  interrupts, 
IBM,  in  the  original  PC,  redefined  usage  of  Interrupts  05H  to  IFH.  Most,  but  not  all,  of 
these  reserved  vectors  are  used  by  software,  rather  than  hardware,  interrupts;  the 
redefined  IBM  uses  are  listed  in  Table  13-2. 

Table  13-1.  Intel  Reserved  Exception  Interrupts. 


Interrupt 

Number  Definition 

OOH  Divide  by  zero 

OlH  Single  step 

02H  Nonmaskable  interrupt  (NMI) 

03H  Breakpoint  trap 

04H  Overflow  trap 

05H  BOUND  range  exceeded* 

06H  Invalid  opcode  * 

07H  Coprocessor  not  available  t 

08H  Double-fault  exceptionf 

09H  Coprocessor  segment  overrun  f 

OAH  Invalid  task  state  segment  (TSS)  t 

OBH  Segment  not  presentf 

OCH  Stack  exception! 

ODH  General  protection  exception! 

OEH  Page  fault! 


(more) 
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Table  13-1.  Continued. 

Interrupt 

Number  Definition 

OFH  (Reserved) 

lOH  Coprocessor  errorf 


*The  80186, 80286,  and  80386  microprocessors  only. 
tThe  80286  and  80386  microprocessors  only. 

+The  80386  microprocessor  only. 

Table  13-2.  IBM  Interrupt  Usage. 


Interrupt 

Number  DeDnition 


05H 

06H 

07H 

OSH 

09H 

OAH 

OBH 

OCH 

ODH 

OEH 

OFH 

lOH 

IIH 

12H 

13H 

14H 

15H 

16H 

17H 

18H 

19H 

lAH 

IBH 

ICH 

IDH 

lEH 

IFH 


Print  screen 

Unused 

Unused 

Hardware  IRQO  (timer-tick)* 
Hardware  IRQl  (keyboard) 
Hardware  IRQ2  (reserved)t 
Hardware  IRQ3  (COM2) 
Hardware  IRQ4(COMl) 
Hardware  IRQ5  (fixed  disk) 
Hardware  IRQ6  (floppy  disk) 
Hardware  IRQ7  (printer) 
Video  service 
Equipment  information 
Memory  size 
Disk  I/O  service 
Serial-port  service 
Cassette/network  service 
Keyboard  service 
Printer  service 
ROM  BASIC 
Restart  system 
Get/Set  time/date 
Control-Break  (user  defined) 
Timer  tick  (user  defined) 
Video  parameter  pointer 
Disk  parameter  pointer 
Graphics  character  table 


•IRQ  =  Interrupt  request  line. 
Table  13-4. 
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Nestled  in  the  middle  of  Table  13-2  are  the  eight  hardware  interrupt  vectors  (08-0FH)  IBM 
implemented  in  the  original  PC  design.  These  eight  vectors  provide  the  maskable  inter¬ 
rupts  for  the  IBM  PC-family  and  close  compatibles.  Additional  IRQ  lines  built  into  the  IBM 
PC/AT  are  discussed  under  The  IRQ  Levels  below. 

The  conflicting  uses  of  the  interrupts  listed  in  Tables  13-1  and  13-2  have  created  com¬ 
patibility  problems  as  the  8086  family  of  microprocessors  has  developed.  For  complete 
compatibility  with  IBM  equipment,  the  IBM  usage  must  be  followed  even  when  it  conflicts 
with  the  chip  design.  For  example,  a  BOUND  error  occurs  if  an  array  index  exceeds  the 
specified  upper  and  lower  limits  (bovmds)  of  the  array,  causing  an  Interrupt  05H  to  be 
generated.  But  the  80286  processor  used  in  all  AT-class  computers  will,  if  a  BOUND  error 
occurs,  send  the  contents  of  the  display  to  the  printer,  because  IBM  uses  Interrupt  05H  for 
the  Print  Screen  function. 


Hardware  Interrupt  Categories 

The  8086  family  of  microprocessors  can  handle  three  types  of  hardware  interrupts.  First 
are  the  internal,  microprocessor-generated  exception  interrupts  (Table  13-1).  Second  is  the 
nonmaskable  interrupt,  or  NMI  (Interrupt  02H),  which  is  generated  when  the  NMI  line 
(pin  17  on  the  8088  and  8086,  pin  59  on  the  80286,  pin  B8  on  the  80386)  goes  high  (active). 
In  the  IBM  PC  family  (except  the  PCjr  and  the  Convertible),  the  nonmaskable  interrupt  is 
designated  for  memory  parity  errors.  Third  are  the  maskable  interrupts,  which  are  usually 
generated  by  external  devices. 

Maskable  interrupts  are  routed  to  the  main  processor  through  a  chip  called  the  8259A 
Programmable  Interrupt  Controller  (PIC).  When  it  receives  an  interrupt  request,  the  PIC 
signals  the  microprocessor  that  an  interrupt  needs  service  by  driving  the  interrupt  request 
(INTR)  line  of  the  main  processor  to  high  voltage  level.  This  article  focuses  on  the  mask¬ 
able  interrupts  and  the  8259A  because  it  is  through  the  PIC  that  external  I/O  devices  (disk 
drives,  serial  communication  ports,  and  so  forth)  gain  access  to  the  interrupt  system. 

Interrupt  priorities  in  the  8086  family 

The  Intel  microprocessors  have  a  built-in  priority  system  for  handling  interrupts  that 
occur  simultaneously.  Priority  goes  to  the  internal  instruction  exception  interrupts,  such  as 
Divide  by  Zero  and  Invalid  Opcode,  because  priority  is  determined  by  the  interrupt  num¬ 
ber:  Interrupt  OOH  takes  priority  over  all  others,  whereas  the  last  possible  interrupt,  OFFH, 
would,  if  present,  never  be  allowed  to  break  in  while  another  interrupt  was  being  serviced. 
However,  if  interrupt  service  is  enabled  (the  microprocessor’s  interrupt  flag  is  set),  any 
hardware  interrupt  takes  priority  over  any  software  interrupt  (INT  instruction). 

The  priority  sequencing  by  interrupt  number  must  not  be  confused  with  the  priority 
resolution  performed  by  hardware  external  to  the  microprocessor.  The  numeric  priority 
discussed  here  applies  only  to  interrupts  generated  within  the  8086  family  of  microproces¬ 
sor  chips  and  is  totally  independent  of  system  interrupt  priorities  established  for  compo¬ 
nents  external  to  the  microprocessor  itself. 


Section  II:  Programming  in  the  MS-DOS  Environment  411 


Part  C:  Customizing  MS-DOS 


Interrupt  service  routines 

For  the  most  part,  programmers  need  not  write  hardware-specific  program  routines  to 
service  the  hardware  interrupts.  The  IBM  PC  BIOS  routines,  together  with  MS-DOS  ser¬ 
vices,  are  usually  sufficient.  In  some  cases,  however,  MS-DOS  and  the  ROM  BIOS  do  not 
provide  enough  assistance  to  ensure  adequate  performance  of  a  program.  Most  notable  in 
this  category  is  communications  software,  for  which  programmers  usually  must  access  the 
8259A  and  the  8250  Universal  Asynchronous  Receiver  and  Transmitter  (UART)  directly. 
See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos: 
Interrupt-Driven  Communications. 


Characteristics  of  Maskable  Interrupts 

Two  major  characteristics  distinguish  maskable  interrupts  from  all  other  events  that  can 
occur  in  the  system:  They  are  totally  unpredictable,  and  they  are  highly  volatile.  In  gener¬ 
al,  a  hardware  interrupt  occurs  when  a  peripheral  device  requires  the  full  attention  of  the 
system  and  data  will  be  irretrievably  lost  unless  the  system  responds  rapidly. 

All  things  are  relative,  however,  and  this  is  especially  true  of  the  speed  required  to  service 
an  interrupt  request.  For  example,  assume  that  two  interrupt  requests  occur  at  essentially 
the  same  time.  One  is  from  a  serial  communications  port  receiving  data  at  300  bps;  the 
other  is  from  a  serial  port  receiving  data  at  9600  bps.  Data  from  the  first  serial  port  will  not 
change  for  at  least  30  milliseconds,  but  the  second  serial  port  must  be  serviced  within  one 
millisecond  to  avoid  data  loss. 

Unpredictability 

Because  maskable  interrupts  generally  originate  in  response  to  external  physical  events, 
such  as  the  receipt  of  a  byte  of  data  over  a  communications  line,  the  exact  time  at  which 
such  an  interrupt  will  occur  cannot  be  predicted.  Even  the  timer  interrupt  request,  which 
by  default  occurs  approximately  18.2  times  per  second,  cannot  be  predicted  by  any  pro¬ 
gram  that  happens  to  be  executing  when  the  interrupt  request  occurs. 

Because  of  this  unpredictability,  the  system  must,  if  it  allows  any  interrupts  to  be  recog¬ 
nized,  be  prepared  to  service  all  maskable  interrupt  requests.  Conversely,  if  interrupts  can¬ 
not  be  serviced,  they  must  all  be  disabled.  The  8086  family  of  microprocessors  provides 
the  Set  Interrupt  Flag  (STI)  instruction  to  enable  maskable  interrupt  response  and  the 
Clear  Interrupt  Flag  (CLI)  instruction  to  disable  it.  The  interrupt  flag  is  also  cleared  auto¬ 
matically  when  a  hardware  interrupt  response  begins;  the  interrupt  handler  should  ex¬ 
ecute  STI  as  quickly  as  possible  to  allow  higher  priority  interrupts  to  be  serviced. 

Volatility 

As  noted  earlier,  a  maskable  interrupt  request  must  normally  be  serviced  immediately  to 
prevent  loss  of  data,  but  the  concept  of  immediacy  is  relative  to  the  data  transfer  rate  of  the 
device  requesting  the  interrupt.  The  rule  is  that  the  currently  available  unit  of  data  must  be 
processed  (at  least  to  the  point  of  being  stored  in  a  buffer)  before  the  next  such  item  can 
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arrive.  Except  for  such  devices  as  disk  drives,  which  always  require  immediate  response, 
interrupts  for  devices  that  receive  data  are  normally  much  more  critical  than  interrupts 
for  devices  that  transmit  data. 

The  problems  imposed  by  data  volatility  during  hardware  interrupt  service  are  solved  by 
establishing  service  priorities  for  interrupts  generated  outside  the  microprocessor  chip  it¬ 
self.  Devices  with  the  slowest  transfer  rates  are  assigned  lower  interrupt  service  priorities, 
and  the  most  time-critical  devices  are  assigned  the  highest  priority  of  interrupt  service. 


Handling  Maskable  Interrupts 

The  microprocessor  handles  all  interrupts  (maskable,  nonmaskable,  and  software)  by 
pushing  the  contents  of  the  flags  register  onto  the  stack,  disabling  the  interrupt  flag,  and 
pushing  the  current  contents  of  the  CS:IP  registers  onto  the  stack. 

The  microprocessor  then  takes  the  interrupt  number  from  the  data  bus,  multiplies  it  by  4 
(the  size  of  each  vector  in  bytes),  and  uses  the  result  as  an  offset  into  the  interrupt  vector 
table  located  in  the  bottom  1  KB  (segment  OOOOH)  of  system  RAM.  The  4-byte  address 
at  that  location  is  then  used  as  the  new  CS:IP  value  (Figure  13-1). 


Figure  13-1.  General  interrupt  sequence. 
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External  devices  are  assigned  dedicated  interrupt  request  lines  (IRQs)  associated  with  the 
8259A.  See  The  IRQ  Levels  below.  When  a  device  requires  attention,  it  sends  a  signal  to 
the  PIC  via  its  IRQ  line.  The  PIC,  which  functions  as  an  “executive  secretary”  for  the  exter¬ 
nal  devices,  operates  as  shown  in  Figure  13-2.  It  evaluates  the  service  request  and,  if  appro¬ 
priate,  causes  the  microprocessor’s  INTR  line  to  go  high.  The  microprocessor  then  checks 
whether  interrupts  are  enabled  (whether  the  interrupt  flag  is  set).  If  they  are,  the  flags  are 
pushed  onto  the  stack,  the  interrupt  flag  is  disabled,  and  CS:IP  is  pushed  onto  the  stack. 


DEVICE  8259A  MICROPROCESSOR 


Figure  13-2.  Maskable  interrupt  service. 
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The  microprocessor  acknowledges  the  interrupt  request  by  signaling  the  8259A  via  the 
interrupt  acknowledge  (INTA)  line.  The  8259A  then  places  the  interrupt  number  on  the 
data  bus.  The  microprocessor  gets  the  interrupt  number  from  the  data  bus  and  services 
the  interrupt.  Before  issuing  the  IRET  instruction,  the  interrupt  service  routine  must  issue 
an  end-of-interrupt  (EOI)  sequence  to  the  8259A  so  that  other  interrupts  can  be  processed. 
This  is  done  by  sending  20H  to  port  20H.  (The  similarity  of  numbers  is  pure  coincidence.) 
The  EOI  sequence  is  covered  in  greater  detail  elsewhere.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Interrupt-Driven  Communications. 

The  8259A  Programmable  Interrupt  Controller 

The  8259A  (Figure  13-3)  has  a  number  of  internal  components,  many  of  them  under  soft¬ 
ware  control.  Only  the  default  settings  for  the  IBM  PC  family  are  covered  here. 

Three  registers  influence  the  servicing  of  maskable  interrupts:  the  interrupt  request  regis¬ 
ter  (IRR),  the  in-service  register  (ISR),  and  the  interrupt  mask  register  (IMR). 

The  IRR  is  used  to  keep  track  of  the  devices  requesting  attention.  When  a  device  causes 
its  IRQ  line  to  go  high  to  signal  the  8259A  that  it  needs  service,  a  bit  is  set  in  the  IRR  that 
corresponds  to  the  interrupt  level  of  the  device. 

The  ISR  specifies  which  interrupt  levels  are  currently  being  serviced;  an  ISR  bit  is  set  when 
an  interrupt  has  been  acknowledged  by  the  CPU  (via  INTA)  and  the  interrupt  number  has 
been  placed  on  the  data  bus.  The  ISR  bit  associated  with  a  particular  IRQ  remains  set  until 
an  EOI  sequence  is  received. 

The  IMR  is  a  read/write  register  (at  port  21H)  that  masks  (disables)  specific  interrupts. 
When  a  bit  is  set  in  this  register,  the  corresponding  IRQ  line  is  masked  and  no  servicing  for 
it  is  performed  until  the  bit  is  cleared.  Thus,  a  particular  IRQ  can  be  disabled  while  all 
others  continue  to  be  serviced. 

The  fourth  major  block  in  Figure  13-3,  labeled  Priority  resolver,  is  a  complex  logical  circuit 
that  forms  the  heart  of  the  8259A.  This  component  combines  the  statuses  of  the  IMR,  the 
ISR,  and  the  IRR  to  determine  which,  if  any,  pending  interrupt  request  should  be  serviced 
and  then  causes  the  microprocessor’s  INTR  line  to  go  high.  The  priority  resolver  can  be 
programmed  in  a  number  of  modes,  although  only  the  mode  used  in  the  IBM  PC  and  close 
compatibles  is  described  here. 
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Figure  13-3  ^  Block  diagram  of  the  8259A  Programmable  Interrupt  Controller. 


The  IRQ  levels 

When  two  or  more  unserviced  hardware  interrupts  are  pending,  the  8259A  determines 
which  should  be  serviced  first.  The  standard  mode  of  operation  for  the  PIC  is  the  fully 
nested  mode,  in  which  IRQ  lines  are  prioritized  in  a  fixed  sequence.  Only  IRQ  lines  with 
higher  priority  than  the  one  currently  being  serviced  are  permitted  to  generate  new 
interrupts. 
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The  highest  priority  is  IRQO,  and  the  lowest  is  IRQ7.  Thus,  if  an  Interrupt  09H  (signaled 
by  IRQl)  is  being  serviced,  only  an  Interrupt  OSH  (signaled  by  IRQO)  can  break  in.  All 
other  interrupt  requests  are  delayed  until  the  Interrupt  09H  service  routine  is  completed 
and  has  issued  an  EOI  sequence. 

Eight-level  designs 

The  IBM  PC,  PCjr,  and  PC/XT  (and  port-compatible  computers)  have  eight  IRQ  lines  to 
the  PIC  chip — IRQO  through  IRQ7.  These  lines  are  mapped  into  interrupt  vectors  for 
Interrupts  OSH  through  OFH  (that  is,  S  +  IRQ  level).  These  eight  IRQ  lines  and  their  associ¬ 
ated  interrupts  are  listed  in  Table  13-3. 


Table  13-3.  Eight-Level  Interrupt  Map. 


IRQ  line 

Interrupt 

Description 

IRQO 

08H 

Timer  tick,  18.2  times  per  second 

IRQl 

09H 

Keyboard  service  required 

IRQ2 

OAH 

I/O  channel  (unused  on  IBM  PC/XT) 

IRQ3 

OBH 

COMl  service  required 

IRQ4 

OCH 

COM2  service  required 

IRQ5 

ODH 

Fixed-disk  service  required 

OEH 

Floppy-disk  service  required 

IRQ7 

OFH 

Data  request  from  parallel  printer* 

*  This  request  cannot  be  reliably  generated  by  older  versions  of  the  IBM  Monochrome/Printer  Adapter  and 
compatibles.  Printer  drivers  that  depend  on  this  signal  for  operation  with  these  cards  are  subject  to  failure. 


Sixteen-level  designs 

In  the  IBM  PC/AT,  S  more  IRQ  levels  have  been  added  by  using  a  second  S259A  PIC  (the 
“slave”)  and  a  cascade  effect,  which  gives  16  priority  levels. 

The  cascade  effect  is  accomplished  by  connecting  the  INT  line  of  the  slave  to  the  IRQ2  line 
of  the  first,  or  “master,”  8259A  instead  of  to  the  microprocessor.  When  a  device  connected 
to  one  of  the  slave’s  IRQ  lines  makes  an  interrupt  request,  the  INT  line  of  the  slave  goes 
high  and  causes  the  IRQ2  line  of  the  master  8259A  to  go  high,  which,  in  turn,  causes  the 
INT  line  of  the  master  to  go  high  and  thus  interrupts  the  microprocessor. 

The  microprocessor,  ignorant  of  the  second  8259A’s  presence,  simply  generates  an  inter¬ 
rupt  acknowledge  signal  on  receipt  of  the  interrupt  from  the  master  8259A.  This  signal  ini¬ 
tializes  both  8259As  and  also  causes  the  master  to  turn  control  over  to  the  slave.  The  slave 
then  completes  the  interrupt  request. 

On  the  IBM  PC/AT,  the  eight  additional  IRQ  lines  are  mapped  to  Interrupts  70H  through 
77H  (Table  13-4).  Because  the  eight  additional  lines  are  effectively  connected  to  the  master 
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8259A’s  IRQ2  line,  they  take  priority  over  the  master’s  IRQ3  through  IRQ7  events.  The 
cascade  effect  is  graphically  represented  in  Figure  13-4. 

Table  13-4.  Sixteen-Level  Interrupt  Map. 


IRQ  line 

Interrupt 

Description 

IRQO 

08H 

Timer  tick,  18.2  times  per  second 

IRQl 

09H 

Keyboard  service  required 

IRQ2 

OAH 

INT  from  slave  8259A: 

IRQ8 

70H 

Real-time  clock  service 

IRQ9 

71H 

Software  redirected  to  IRQ2 

IRQIO 

72H 

Reserved 

IRQll 

73H 

Reserved 

IRQ12 

74H 

Reserved 

IRQ13 

75H 

Numeric  coprocessor 

IRQ14 

76H 

Fixed-disk  controller 

IRQ15 

77H 

Reserved 

IRQ3 

OBH 

COM2  service  required 

IRQ4 

OCH 

COMl  service  required 

IRQ5 

ODH 

Data  request  from  LPT2 

IRQ6 

OEH 

Floppy-disk  service  required 

IRQ7 

OFH 

Data  request  from  LPTl 
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Note:  During  the  INTA  sequence,  the  corresponding  bit  in  the  ISR  register  of  both  8259As 
is  set,  so  two  EOIs  must  be  issued  to  complete  the  interrupt  service — one  for  the  slave  and 
one  for  the  master. 


Programming  for  the  Hardware  Interrupts 

Any  program  that  modifies  an  interrupt  vector  must  restore  the  vector  to  its  original  condi¬ 
tion  before  returning  control  to  MS-DOS  (or  to  its  parent  process).  Any  program  that  totally 
replaces  an  existing  hardware  interrupt  handler  with  one  of  its  own  must  perform  all  the 
handshaking  and  terminating  actions  of  the  original — re-enable  interrupt  service,  signal 
EOI  to  the  interrupt  controller,  and  so  forth.  Failure  to  follow  these  rules  has  led  to  many 
hours  of  programmer  frustration.  See  also  PROGRAMMING  IN  THE  MS-DOS  ENVIRON¬ 
MENT:  Customizing  ms-dos:  Exception  Handlers. 

When  an  existing  interrupt  handler  is  completely  replaced  with  a  new,  customized  rou¬ 
tine,  the  existing  vector  must  be  saved  so  it  can  be  restored  later.  Although  it  is  possible  to 
modify  the  4-byte  vector  by  directly  addressing  the  vector  table  in  low  RAM  (and  many 
published  programs  have  followed  this  practice),  any  program  that  does  so  runs  the  risk 
of  causing  system  failure  when  the  program  is  used  with  multitasking  or  multiuser  en¬ 
hancements  or  with  future  versions  of  MS-DOS.  The  only  technique  that  can  be  recom¬ 
mended  for  either  obtaining  the  existing  vector  values  or  changing  them  is  to  use  the 
MS-DOS  functions  provided  for  this  purpose:  Interrupt  21H  Functions  25H  (Set  Interrupt 
Vector)  and  35H  (Get  Interrupt  Vector). 

After  the  existing  vector  has  been  saved,  it  can  be  replaced  with  a  far  pointer  to  the 
replacement  routine.  The  new  routine  must  end  with  an  IRET  instruction.  It  should  also 
take  care  to  preserve  all  microprocessor  registers  and  conditions  at  entry  and  restore 
them  before  returning. 

A  sample  replacement  handler 

Suppose  a  program  performs  many  mathematical  calculations  of  random  values.  To 
prevent  abnormal  termination  of  the  program  by  the  default  MS-DOS  Interrupt  OOH  han¬ 
dler  when  a  DIV  or  IDIV  instruction  is  attempted  and  the  divisor  is  zero,  a  programmer 
might  want  to  replace  the  Interrupt  OOH  (Divide  by  Zero)  routine  with  one  that  informs  the 
user  of  what  has  happened  and  then  continues  operation  without  abnormal  termination. 
The  .COM  program  DIVZERO.ASM  (Figure  13-5)  does  just  that.  (Another  example  is  in¬ 
cluded  in  the  article  on  interrupt-driven  communications.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Interrupt-Driven  Communications.) 
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name  divzero 

title  'DIVZERO  -  Interrupt  OOH  Handler' 

DIVZERO. ASM:  Demonstration  Interrupt  OOH  Handler 

To  assemble,  link,  and  convert  to  COM  file: 

OMASM  DIVZERO;  <Enter> 

OLINK  DIVZERO;  <Enter> 

OEXE2BIN  DIVZERO.EXE  DIVZERO.COM  <Enter> 
ODEL  DIVZERO.EXE  <Enter> 


cr 

equ 

Odh 

; 

ASCII  carriage  return 

If 

equ 

Oah 

; 

ASCII  linefeed 

eos 

equ 

'$' 

'• 

end  of  string  marker 

-TEXT 

segment 

word  public 

'CODE 

assume 

cs :_TEXT, ds 

:_TEXT, 

es :_TEXT, ss :_TEXT 

org 

lOOh 

entry : 

jmp 

start 

skip  over  data  area 

intmsg 

db 

'Divide  by 

Zero  Occurred! ', cr, If , eos 

divmsg 

db 

'Dividing  ' 

; 

message  used  by  demo 

pari 

db 

'OOOOh' 

; 

dividend  goes  here 

db 

'  by  ' 

par2 

db 

'OOh' 

; 

divisor  goes  here 

db 

'  equals  ' 

par3 

db 

'OOh' 

; 

quotient  here 

db 

'  remainder 

1 

par4 

db 

'OOh' 

; 

and  remainder  here 

db 

cr, If, eos 

oldintO 

dd 

7 

save  old  Int  OOH  vector 

intflag  db 

0 

; 

nonzero  if  divide  by 

zero  interrupt  occurred 

oldip 

dw 

0 

; 

save  old  IP  value 

;  The  routine  'intO'  is  the  actual  divide  by  zero 
;  interrupt  handler.  It  gains  control  whenever  a 
;  divide  by  zero  or  overflow  occurs.  Its  action 
;  is  to  set  a  flag  and  then  increment  the  instruction 
;  pointer  saved  on  the  stack  so  that  the  failing 


(more) 

Figure  13-5.  The  Divide  by  Zero  replacement  handler,  DIVZERO.  ASM.  This  code  is  specific  to  80286 and 
80386 microprocessors.  (See  Appendix  M:  8086/8088  Software  Compatibility  Issues.) 
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divide  will  not  be  reexecuted  after  the  IRET. 

In  this  particular  case  we  can  call  MS-DOS  to 
display  a  message  during  interrupt  handling 
because  the  application  triggers  the  interrupt 
intentionally.  Thus,  it  is  known  that  MS-DOS  or 
other  interrupt  handlers  are  not  in  control 
at  the  point  of  interrupt. 


into : 


pop 


cs : oldip 


;  capture  instruction  pointer 


push 

push 

push 

push 

push 

push 

push 

push 

push 

pop 

mov 

mov 

int 

add 


pop 

pop 

pop 

pop 

pop 

pop 

pop 

pop 

push 


ax 

bx 

cx 

dx 

di 

si 

ds 

es 

cs 

ds 


;  set  DS  =  CS 


ah,09h 

dx, offset  -TEXT; 
21h 

oldip, 2 


;  print  error  message 
intmsg 


intflag,  1 

es 

ds 

si 

di 

dx 

cx 

bx 

ax 

cs : oldip 


;  bypass  instruction  causing 
;  divide  by  zero  error 

;  set  divide  by  0  flag 

;  restore  all  registers 


;  restore  instruction  pointer 
;  return  from  interrupt 


;  The  code  beginning  at  'start'  is  the  application 
;  program.  It  alters  the  vector  for  Interrupt  OOH  to 
;  point  to  the  new  handler,  carries  out  some  divide 

Figure  13-5.  Continued.  (more) 
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;  operations  (including  one  that  will  trigger  an 
;  interrupt)  for  demonstration  purposes,  restores 
;  the  original  contents  of  the  Interrupt  OOH  vector, 
;  and  then  terminates. 


start:  mov  ax,3500h 

int  21h 


;  get  current  contents 
;  of  Int  OOH  vector 


;  save  segment : of f set 
;  of  previous  Int  OOH  handler 
mov  word  ptr  oldintO,bx 

mov  word  ptr  oldint0+2,es 


;  install  new  handler... 


mov 

dx, offset  into 

;  DS:DX  = 

handler 

address 

mov 

ax, 2500h 

;  call  MS- 

-DOS  to 

set 

int 

21h 

;  Int  OOH 

vector 

;  now  our  handler  is  active, 

;  carry  out  some  test  divides. 


mov 

ax,20h 

; 

test  divide 

mov 

bx,  1 

; 

divide  by  1 

call 

divide 

mov 

ax,1234h 

; 

test  divide 

mov 

bx, 5eh 

; 

divide  by  5EH 

call 

divide 

mov 

ax, 5678h 

test  divide 

mov 

bx,7fh 

; 

divide  by  127 

call 

divide 

mov 

ax, 20h 

* 

test  divide 

mov 

bx,  0 

; 

divide  by  0 

call 

divide 

(triggers  interrupt) 

; 

demonstration  complete, 

restore  old  handler 

Ids 

dx, oldintO 

DS:DX  =  handler  address 

mov 

ax, 2500h 

call  MS-DOS  to  set 

int 

21h 

Int  OOH  vector 

mov 

ax, 4c00h 

• 

final  exit  to  MS-DOS 

int 

21h 

; 

with  return  code  =  0 

;  The  routine  'divide'  carries  out  a  trial  division, 

;  displaying  the  arguments  and  the  results.  It  is 

Figure  13-5.  Continued.  (more) 
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;  called  with  AX  =  dividend  and  BL  =  divisor. 


divide 


nodiv: 


proc 

near 

push 

push 

ax  ; 

bx 

save  arguments 

mov 

call 

di, offset  pari  ; 
wtoa  ; 

convert  dividend  to 

ASCII  for  display 

mov 

mov 

call 

ax,bx  ; 
di, offset  par2  ; 
btoa 

convert  divisor  to 

ASCII  for  display 

pop 

pop 

bx  ; 

ax 

restore  arguments 

div 

cmp 

jne 

bl 

intflag,0  ; 

nodiv  ; 

perform  the  division 
divide  by  zero  detected? 
yes,  skip  display 

push 

mov 

call 

ax  ; 

di, offset  par3  ; 
btoa 

no,  convert  quotient  to 
ASCII  for  display 

pop 

xchg 

mov 

call 

ax  ; 

ah,al  ; 

di, offset  par4 
btoa 

convert  remainder  to 
ASCII  for  display 

mov 

mov 

int 

ah,09h 

dx, offset  divmsg 
21h 

show  arguments,  results 

mov 

ret 

intflag,0  ; 

clear  divide  by  0  flag 
and  return  to  caller 

divide  endp 


wtoa  proc  near 


push  ax 

mov  al,ah 

call  btoa 

add  di , 2 


;  convert  word  to  hex  ASCII 
;  call  with  AX  =  binary  value 
;  DI  =  addr  for  string 

;  returns  AX,  CX,  DI  destroyed 

;  save  original  value 

;  convert  upper  byte 
;  increment  output  address 


Figure  13-5.  Continued. 
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pop  ax 

call  btoa 

ret 

wtoa  endp 


;  convert  lower  byte 
;  return  to  caller 


btoa  proc  near 


mov 

ah,  al 

mov 

CX,  4 

shr 

al,  cl 

call 

ascii 

mov 

[di],al 

mov 

al,  ah 

and 

al,0fh 

call 

ascii 

mov 

[di+1 ] ,al 

ret 

btoa 

endp 

ascii 

proc 

near  ; 

add 

o 

1— 1 

cmp 

al, ’9' 

jle 

ascii2 

add 

al,'A'-'9'-1 

ascii2 : 

ret 

ascii 

endp 

-TEXT 

ends 

end 

entry 

convert  byte  to  hex  ASCII 
call  with  AL  =  binary  value 

DI  =  addr  to  store  string 
returns  AX,  CX  destroyed 

save  lower  nibble 
shift  right  4  positions 
to  get  upper  nibble 
convert  4  bits  to  ASCII 
store  in  output  string 
get  back  lower  nibble 

blank  out  upper  one 
convert  4  bits  to  ASCII 
store  in  output  string 
back  to  caller 


convert  AL  bits  0-3  to 
ASCII  {0. . .9,A. . .F} 
and  return  digit  in  AL 

"fudge  factor”  for  A-F 
return  to  caller 


Figure  13-5.  Continued. 


Supplementary  handlers 

In  many  cases,  a  custom  interrupt  handler  augments,  rather  than  replaces,  the  existing 
routine.  The  added  routine  might  process  some  data  before  passing  the  data  to  the  exist¬ 
ing  routine,  or  it  might  do  the  processing  afterward.  These  cases  require  slightly  different 
coding  for  the  handler. 

If  the  added  routine  is  to  process  data  before  the  existing  handler  does,  the  routine  need 
only  jump  to  the  original  handler  after  completing  its  processing.  This  jump  can  be  done 
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indirectly,  with  the  same  pointer  used  to  save  the  original  content  of  the  vector  for  restor¬ 
ation  at  exit.  For  example,  a  replacement  Interrupt  OSH  handler  that  merely  increments  an 
internal  flag  at  each  timer  tick  can  look  something  like  the  following: 


myflag  dw 


;  variable  to  be  incremented 
;  on  each  timer-tick  interrupt 


oldintS  dd  ? 


;  contains  address  of  previous 
;  timer-tick  interrupt  handler 


mov  ax,3508h 

int  21  h 

mov  word  ptr  oldintS, bx 

mov  word  ptr  oldint8+2,es 

mov  dx,seg  myintS 

mov  ds , dx 

mov  dx, offset  myintS 

mov  ax,2508h 

int  21h 


get  the  previous  contents 
of  the  Interrupt  OSH  vector. . . 
AH  =  35H  (Get  Interrupt  Vector) 
AL  =  Interrupt  number  (OSH) 
save  the  address  of 
the  previous  Int  OSH  Handler 
put  address  of  the  new 
interrupt  handler  into  DS:DX 
and  call  MS-DOS  to  set  vector 
AH  =  25H  (Set  Interrupt  Vector) 
AL  =  Interrupt  number  (OSH) 


myintS : 


;  this  is  the  new  handler 
;  for  Interrupt  OSH 


inc  cs:myflag 


;  increment  variable  on  each 
;  timer-tick  interrupt 


jmp  dword  ptr  cs: [oldintS]  ;  then  chain  to  the 

;  previous  interrupt  handler 


The  added  handler  must  preserve  all  registers  and  machine  conditions,  except  those 
machine  conditions  it  will  modify,  such  as  the  value  of  myflag  in  the  example  (and  the 
flags  register,  which  is  saved  by  the  interrupt  action),  and  it  must  restore  those  registers 
and  conditions  before  performing  the  jump  to  the  original  handler. 

A  more  complex  situation  arises  when  a  replacement  handler  does  some  processing  after 
the  original  routine  executes,  especially  if  the  replacement  handler  is  not  reentrant.  To 
allow  for  this  processing,  the  replacement  handler  must  prevent  nested  interrupts,  so  that 
even  if  the  old  handler  (which  is  chained  to  the  replacement  handler  by  a  CALL  instruc¬ 
tion)  issues  an  EOI,  the  replacement  handler  will  not  be  interrupted  during  postprocess¬ 
ing.  For  example,  instead  of  using  the  preceding  Interrupt  OSH  example  routine,  the 
programmer  could  use  the  following  code  to  implement  myflag  as  a  semaphore  and 
use  the  XCHG  instruction  to  test  it: 
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myintS : 

mov  ax,l 

xchg  cs:myflag,ax 

push  ax 

pushf 

call  dword  ptr  cs:oldint8 

pop  ax 

or  ax, ax 


jnz  myint8x 


mov  cs:myflag,0 


myint8x; 

iret 


;  this  is  the  new  handler 
;  for  Interrupt  08H 

;  test  and  set  interrupt- 
;  handling-in-progress  semaphore 

;  save  the  semaphore 

;  simulate  interrupt,  allowing 
;  the  previous  handler  for  the 
;  Interrupt  OSH  vector  to  run 

;  get  the  semaphore  back 
;  is  our  interrupt  handler 
;  already  running? 

;  yes,  skip  this  one 

;  now  perform  our  interrupt 
;  processing  here... 

;  clear  the  interrupt-handling- 
;  in-progress  flag 

;  return  from  interrupt 


Note  that  an  interrupt  handler  of  this  type  must  simulate  the  original  call  to  the  interrupt 
routine  by  first  doing  a  PUSHF,  followed  by  a  far  CALL  via  the  saved  pointer  to  execute  the 
original  handler  routine.  The  flags  register  pushed  onto  the  stack  is  restored  by  the  IRET 
of  the  original  handler.  Upon  return  from  the  original  code,  the  new  routine  can  preserve 
the  machine  state  and  do  its  own  processing,  finally  returning  to  the  caller  by  means 
of  its  own  IRET. 


The  flags  inside  the  new  routine  need  not  be  preserved,  as  they  are  automatically  restored 
by  the  IRET  instruction.  Because  of  the  nature  of  interrupt  servicing,  the  service  routine 
should  not  depend  on  any  information  in  the  flags  register,  nor  can  it  return  any  informa¬ 
tion  in  the  flags  register.  Note  also  that  the  previous  handler  (invoked  by  the  indirect 
CALL)  will  almost  certainly  have  dismissed  the  interrupt  by  sending  an  EOI  to  the  8259A 
PIC.  Thus,  the  machine  state  is  not  the  same  as  in  the  first  myintS  example. 

To  remove  the  new  vector  and  restore  the  original,  the  program  simply  replaces  the  new 
vector  (in  the  vector  table)  with  the  saved  copy.  If  the  substituted  routine  is  part  of  an 
application  program,  the  original  vector  must  be  restored  for  every  possible  method  of 
exiting  from  the  program  (including  Control-Break,  Control-C,  and  critical-error  Abort 
exits).  Failure  to  observe  this  requirement  invariably  results  in  system  failure.  Even  though 
the  system  failure  might  be  delayed  for  some  timp  after  the  exit  from  the  offending  pro¬ 
gram,  when  some  subsequent  program  overlays  the  interrupt  handler  code  the  crash 
will  be  imminent. 
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Summary 

Hardware  interrupt  handler  routines,  although  not  strictly  a  part  of  MS-DOS,  form  an 
integral  part  of  many  MS-DOS  programs  and  are  tightly  constrained  by  MS-DOS  require¬ 
ments.  Routines  of  this  type  play  important  roles  in  the  functioning  of  the  IBM  personal 
computers,  and,  with  proper  design  and  programming,  significantly  enhance  product 
reliability  and  performance.  In  some  instances,  no  other  practical  method  exists  for 
meeting  performance  requirements. 


Jim  Kyle 
Chip  Rabinowitz 
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Article  14 

Writing  MS-DOS  Filters 


A  filter  is,  essentially,  a  program  that  operates  on  a  stream  of  characters.  The  source  and 
destination  of  the  character  stream  can  be  files,  another  program,  or  almost  any  character 
device.  The  transformation  applied  by  the  filter  to  the  character  stream  can  range  from  an 
operation  as  simple  as  substituting  a  character  set  to  an  operation  as  elaborate  as  gener¬ 
ating  splines  from  sets  of  coordinates. 

The  standard  MS-DOS  paclcage  includes  three  simple  filters:  SORT,  which  alphabetically 
sorts  text  on  a  line-by-line  basis;  FIND,  which  searches  a  text  stream  to  match  a  specified 
string;  and  MORE,  which  displays  text  one  screenful  at  a  time.  This  article  describes  how 
filters  work  and  how  new  ones  can  be  constructed.  See  also  USER  COMMANDS:  find; 

MORE;  SORT. 


System  Support  for  Filters 

The  operation  of  a  filter  program  relies  on  two  features  that  appeared  in  MS-DOS  version 
2.0:  standard  devices  and  redirectable  I/O. 

The  standard  devices  are  represented  by  five  handles  that  are  originally  established  when 
the  system  is  initialized.  Each  process  inherits  these  handles  from  its  immediate  parent. 
Thus,  the  standard  device  handles  are  already  opened  when  a  process  acquires  control  of 
the  system,  and  the  process  can  use  the  handles  with  Interrupt  21H  Functions  3FH  and 
40H  for  read  and  write  operations  without  further  preliminaries.  The  default  assignments 
of  the  standard  device  handles  are 


Handle  Name  Default  Device 


0 

stdin  (standard  input) 

CON 

1 

stdout  (standard  output) 

CON 

2 

stderr  (standard  error) 

CON 

3 

stdaux  (standard  auxiliary) 

AUX 

4 

stdlst  (standard  list) 

PRN 

The  CON  device  is  assigned  by  default  to  the  system’s  keyboard  and  video  display.  AUX 
is  assigned  by  default  to  COMl  (the  first  physical  serial  port),  and  PRN  is  assigned  by 
default  to  LPTl  (the  first  physical  parallel  printer  port);  in  some  systems  these  assign¬ 
ments  can  be  altered  with  the  MODE  command.  See  PROGRAMMING  IN  THE  MS-DOS 
ENVIRONMENT:  Programming  for  ms-dos:  Character  Device  Input  and  Output;  USER 
COMMANDS:  mode;  ctty. 
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When  a  program  is  executed  by  entering  its  name  at  the  system  (COMMAND.COM) 
prompt,  the  user  can  redirect  either  or  both  of  the  standard  input  and  standard  output  han¬ 
dles  from  their  default  device  (CON)  to  another  file,  a  character  device,  or  a  process.  This 
redirection  is  accomplished  by  including  one  of  the  special  characters  <,  >,  »,  or  1  in  the 
command  line,  in  the  following  form: 


Redirection  Result 

<  file  Contents  of  the  specified  file  are  used  instead  of  the  keyboard  as  the  pro¬ 

gram’s  standard  input. 

<  device  Program  takes  its  standard  input  from  the  named  device  instead  of  from 

the  keyboard. 

>  device  Program  sends  its  standard  output  to  the  named  device  instead  of  to  the 

video  display. 

>  file  Program  sends  its  standard  output  to  the  specified  file  instead  of  to  the 

video  display. 

»  file  Program  appends  its  standard  output  to  the  current  contents  of  the  speci¬ 

fied  file  instead  of  to  the  video  display. 

pi  1  p2  Standard  output  of  program  pi  is  routed  to  become  the  standard  input  of 

program  p2  (output  of  pi  is  said  to  be  piped  to  p2X 

For  example,  the  command 

OSORT  <  MYFILE.TXT  >  PRN  <Enter> 

causes  the  SORT  filter  to  read  its  input  from  the  file  MYFILE.TXT,  sort  the  lines  alpha¬ 
betically,  and  write  resulting  text  to  the  character  device  PRN  (the  logical  name  for  the 
system’s  list  device). 

The  redirection  requested  by  the  <,  >, »,  or  1  characters  takes  place  at  the  level  of 
COMMAND.COM  and  is  invisible  to  the  program  it  affects.  Such  redirection  can  also  be 
put  into  effect  by  another  process.  See  Using  a  Filter  as  a  Child  Process  below. 

Note  that  if  a  program  “goes  around”  MS-DOS  to  perform  its  input  and  output,  either  by 
calling  ROM  BIOS  functions  or  by  manipulating  the  keyboard  or  video  controller  directly, 
redirection  commands  placed  in  the  program’s  command  line  do  not  have  the  expected 
effect. 


How  Filters  Work 

By  convention,  a  filter  program  reads  its  text  from  standard  input  and  writes  the  results  of 
its  operations  to  standard  output.  When  the  end  of  the  input  stream  is  reached,  the  filter 
simply  terminates,  optionally  writing  an  end-of-file  mark  (lAH)  to  the  output  stream.  As  a 
result,  filters  are  both  flexible  and  simple. 

Filter  programs  are  flexible  because  they  do  not  know,  and  do  not  care,  about  the  source 
of  the  data  they  process  or  the  destination  of  their  output.  Any  redirection  that  the  user 
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specifies  in  the  command  line  is  invisible  to  the  filter.  Thus,  any  character  device  that  has 
a  logical  name  within  the  system  (CON,  AUX,  COMl,  COM2,  PRN,  LPTl,  LPT2,  LPT3,  and 
so  on),  any  file  on  any  block  device  (local  or  network)  known  to  the  system,  or  any  other 
program  can  supply  a  filter’s  input  or  accept  its  output.  If  necessary,  several  functionally 
simple  filters  can  be  concatenated  with  pipes  to  perform  very  complex  operations. 

Although  flexible,  filters  are  also  simple  because  they  rely  on  their  parent  process  to 
supply  standard  input  and  standard  output  handles  that  have  already  been  appropriately 
redirected.  The  parent  is  responsible  for  opening  or  creating  any  necessary  files,  checking 
the  validity  of  logical  character  device  names,  and  loading  and  executing  the  preceding  or 
following  process  in  a  pipe.  The  filter  need  only  concern  itself  with  the  transformation  it 
will  apply  to  the  data;  it  can  leave  the  I/O  details  to  the  operating  system  and  to  its  parent. 


Building  a  Filter 

Creating  a  new  filter  for  MS-DOS  is  a  straightforward  process.  In  its  simplest  form,  a  filter 
need  only  use  the  handle-oriented  read  (Interrupt  21H  Function  3FH)  and  write  (Interrupt 
21H  Function  40H)  functions  to  get  characters  or  lines  from  standard  input  and  send  them 
to  standard  output,  performing  any  desired  alterations  on  the  text  stream  on  a  character- 
by-character  or  line-by-line  basis. 

Figures  14-1  through  14-4  contain  template  character-oriented  and  line-oriented  filters 
in  both  assembly  language  and  C.  The  C  version  of  the  character  filter  runs  much  faster 
than  the  assembly-language  version,  because  the  C  run-time  library  provides  hidden 
blocking  and  deblocking  (buffering)  of  character  reads  and  writes;  the  assembly-language 
program  actually  makes  two  calls  to  MS-DOS  for  each  character  processed.  (Of  course,  if 
buffering  is  added  to  the  assembly-language  version  it  will  be  both  faster  and  smaller  than 
the  C  filter.)  The  C  and  assembly-language  versions  of  the  line-oriented  filter  run  at 
roughly  the  same  speed. 

name  protoc 

title  'PROTOC. ASM  -  template  character  filter' 

;  PROTOC. ASM:  a  template  for  a  character-oriented  filter. 


Ray  Duncan,  June  1987 


stdin 

equ 

0 

stdout 

equ 

1 

stderr 

equ 

2 

cr 

equ 

Odh 

If 

equ 

Oah 

;  standard  input 
;  standard  output 
;  standard  error 

;  ASCII  carriage  return 
;  ASCII  linefeed 


Figure  14-1.  Assembly-language  template for  a  character-oriented filter  (file  PROTOC.  ASM). 
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DGROUP  group  —DATA, STACK  ;  ‘automatic  data  group' 


—TEXT  segment  byte  public  'CODE* 

assume  cs TEXT, ds : DGROUP, ss : STACK 


main 

proc 

far 

entry  point  from  MS-DOS 

mov 

ax, DGROUP 

set  DS  =  our  data  segment 

mov 

ds,  ax 

maini : 

• 

read  a  character  from  standard  input 

mov 

dx, offset 

DGROUP : 

char  ;  address  to  place  character 

mov 

cx,  1 

; 

length  to  read  =  1 

mov 

bx, stdin 

; 

handle  for  standard  input 

mov 

ah,3fh 

; 

function  3FH  =  read  from  file  or  device 

int 

21h 

; 

transfer  to  MS-DOS 

jc 

main3 

; 

error,  terminate 

cmp 

ax,  1 

; 

any  character  read? 

jne 

main2 

end  of  file,  terminate  program 

call 

transit 

translate  character  if  necessary 

f 

now  write  character  to  standard  output 

mov 

dx, offset 

DGROUP : 

char  ;  address  of  character 

mov 

cx,  1 

f 

length  to  write  =  1 

mov 

bx, stdout 

} 

handle  for  standard  output 

mov 

ah,40h 

; 

function  40H  =  write  to  file  or  device 

int 

21h 

t 

transfer  to  MS-DOS 

jc 

main3 

f 

error,  terminate 

cmp 

ax,  1 

; 

was  character  written? 

jne 

main3 

; 

disk  full,  terminate  program 

jmp 

maini 

go  process  another  character 

main2 : 

mov 

ax, 4c00h 

f 

end  of  file  reached,  terminate 

int 

21h 

program  with  return  code  =  0 

main3 ; 

mov 

ax, 4c01 h 

; 

error  or  disk  full,  terminate 

int 

21h 

'• 

program  with  return  code  =  1 

main 

endp 

; 

end  of  main  procedure 

;  Perform  any  necessary  translation  on  character  from  input, 

;  stored  in  'char'.  Template  action;  leave  character  unchanged. 

transit  proc  near 

ret  ;  template  action:  do  nothing 

transit  endp 

Figure  14-1.  Continued. 
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-TEXT  ends 

—DATA  segment  word  public  'DATA' 

char  db  0  ;  temporary  storage  for  input  character 

—DATA  ends 

STACK  segment  para  stack  'STACK' 
dw  64  dup  (?) 

STACK  ends 

end  main  ;  defines  program  entry  point 

Figure  14-1.  Continued. 


/* 

PROTOC.C:  a  template  for  a  character-oriented  filter. 

Ray  Duncan,  June  1 987 

*/ 

#include  <stdio.h> 

main (argc, argv) 
int  argc; 
char  *argv[]; 

{  char  ch; 

while  (  (ch=getchar ( ) ) ! =EOF  ) 

{  ch=translate (ch) ; 

put char (ch) ; 

} 

exit  (0) ; 

} 

/* 

Perform  any  necessary  translation  on  character  from 
input  file.  Template  action  just  returns  same  character. 

*/ 

int  translate (ch) 
char  ch; 

{  return  (ch) ; 

} 

Figure  14-2.  C  template  for  a  character-oriented  filter  (file  PROTOC.  C). 


/*  read  a  character  */ 

/*  translate  it  if  necessary  */ 
/*  write  the  character  */ 

/*  terminate  at  end  of  file  */ 
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name 

title 

protol 

'PROTOL. ASM  - 

template  line  filter' 

;  PROTOL. ASM: 

a  template  for  a 

line-oriented  filter. 

;  Ray  Duncan, 

June  1 987 

stdin 

equ 

0 

;  standard  input 

stdout 

equ 

1 

;  standard  output 

stderr 

equ 

2 

;  standard  error 

cr 

equ 

Odh 

;  ASCII  carriage  return 

If 

equ 

Oah 

;  ASCII  linefeed 

□GROUP 

group 

-DATA, STACK 

;  'automatic  data  group 

-TEXT 

segment 

byte  public  'CODE 

1 

assume 

cs : -TEXT , ds : DGROUP , es : DGROUP ,  s s : STACK 

main 

proc 

far 

entry  point  from  MS-DOS 

mov 

ax, DGROUP 

/ 

set  DS  =  ES  =  our  data  segment 

mov 

ds,  ax 

mov 

es,  ax 

maini  : 

read  a  line  from  standard  input 

mov 

dx, offset 

DGROUP : 

input  ;  address  to  place  data 

mov 

cx, 256 

max  length  to  read  =  256 

mov 

bx, stdin 

handle  for  standard  input 

mov 

ah,3fh 

function  3FH  =  read  from  file  or  device 

int 

21h 

transfer  to  MS-DOS 

jc 

main3 

if  error,  terminate 

or 

ax,  ax 

any  characters  read? 

jz 

main2 

end  of  file,  terminate  program 

call 

transit 

translate  line  if  necessary 

or 

ax,  ax 

anything  to  output  after  translation? 

jz 

maini 

no,  get  next  line 

now  write  line  to  standard  output 

mov 

dx, offset 

DGROUP : 

output  ;  address  of  data 

mov 

cx,  ax 

length  to  write 

mov 

bx, stdout 

handle  for  standard  output 

mov 

ah,40h 

function  40H  =  write  to  file  or  device 

int 

21h 

transfer  to  MS-DOS 

jc 

main3 

if  error,  terminate 

Figure  14-3 >  Assembly-language  template  for  a  line-oriented  filter  (file  PROTOL  ASM). 
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cmp 

jne 

jmp 

ax,  cx 

main3 

maini 

;  was  entire  line  written? 

;  disk  full,  terminate  program 
;  go  process  another  line 

main2 : 

mov 

int 

ax, 4c00h 

21h 

;  end  of  file  reached,  terminate 
;  program  with  return  code  =  0 

mainS : 

mov 

int 

ax, 4c01 h 

21h 

;  error  or  disk  full,  terminate 
program  with  return  code  =  1 

main 

endp 

;  end  of  main  procedure 

Perform  any  necessary  translation  on  line  stored  in 
'input'  buffer,  leaving  result  in  'output'  buffer. 

Call  with:  AX  =  length  of  data  in  'input'  buffer. 

Return:  AX  =  length  to  write  to  standard  output. 

Action  of  template  routine  is  just  to  copy  the  line. 


transit 

proc 

near 

;  just  copy  line  from  input  to  output 

mov 

si, offset 

DGROUP : input 

mov 

di, offset 

DGROUP : output 

mov 

cx,  ax 

rep  movsb 

ret 

;  return  length  in  AX  unchanged 

transit 

endp 

_TEXT 

ends 

_DATA 

segment 

word  public 

'DATA' 

input 

db 

256  dup  (?) 

;  storage 

for 

input  line 

output 

db 

256  dup  (?) 

;  storage 

for 

output  line 

_DATA 

ends 

STACK 

segment 

para  stack  ' 

'  STACK ' 

dw  64  dup  (?) 

STACK  ends 


end  main  ;  defines  program  entry  point 

Figure  14-3.  Continued. 
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/* 

PROTOL.C:  a  template  for  a  line-oriented  filter. 

Ray  Duncan,  June  1987, 

*/ 

#include  <stdio.h> 

static  char  input [256]; 
static  char  output [256]; 

main (argc, argv) 
int  argc; 
char  *argv[]; 

{  while (  gets (input)  !=  NULL  )  /*  get  a  line  from  input  stream  */ 

/*  perform  any  necessary  translation 
and  possibly  write  result  */ 

{  if  (translate  0 )  puts (output) ; 

} 

exit(O);  /*  terminate  at  end  of  file  */ 


/*  buffer  for  input  line  */ 
/*  buffer  for  output  line  */ 


Perform  any  necessary  translation  on  input  line,  leaving 
the  resulting  text  in  output  buffer.  Value  of  function 
is  'true'  if  output  buffer  should  be  written  to  standard  output 
by  main  routine,  'false'  if  nothing  should  be  written. 


translate () 

{  St rcpy (output, input) ; 

return ( 1 ) ; 

} 


/*  template  action  is  copy  input  */ 
/♦  line  and  return  true  flag  */ 


Figure  14-4.  C  template  for  a  line-oriented  filter  (file  PROTOL.C). 

Each  of  the  four  template  filters  can  be  assembled  or  compiled,  linked,  and  run  exactly  as 
they  are  shown  in  Figures  14-1  through  14-4.  Of  course,  in  this  form  they  function  like  an 
incredibly  slow  COPY  command. 

To  obtain  a  filter  that  does  something  useful,  a  routine  that  performs  some  modification 
of  the  text  stream  that  is  flowing  by  must  be  inserted  between  the  reads  and  writes.  For 
example.  Figures  14-5  and  14-6  contain  the  assembly-language  and  C  source  code  for  a 
character-oriented  filter  named  LC.  This  program  converts  all  uppercase  input  characters 
(A-Z)  to  lowercase  (a-z)  output,  leaving  other  characters  unchanged.  The  only  difference 
between  LC  and  the  template  character  filter  is  the  translation  subroutine  that  operates 
on  the  text  stream. 


436  The  MS-DOS  Encyclopedia 


Article  14:  Writing  MS-DOS  Filters 


name  Ic 

title  'LC.ASM  -  lowercase  filter' 

LC.ASM:  a  simple  character-oriented  filter  to  translate 

all  uppercase  {A-Z}  to  lowercase  {a-z}. 

Ray  Duncan,  June  1987 


stdin 

equ 

0 

;  standard  input 

stdout 

equ 

1 

;  standard  output 

stderr 

equ 

2 

;  standard  error 

cr 

equ 

Odh 

;  ASCII  carriage  return 

If 

equ 

Oah 

;  ASCII  linefeed 

DGROUP 

group 

-DATA, STACK 

;  'automatic  data  group 

-TEXT 

segment 

byte  public 

' CODE ' 

assume 

cs:-TEXT,ds: 

:  DGROUP, ss: STACK 

main 

proc 

far 

;  entry  point  from  MS-DOS 

mov 

ax, DGROUP 

;  set  DS  =  our  data  segment 

mov 

ds,  ax 

maini : 

;  read  a  character  from  standard  input 

mov 

dx, offset 

DGROUP: char  ;  address  to  place  character 

mov 

cx,  1 

;  length  to  read  =  1 

mov 

bx, stdin 

;  handle  for  standard  input 

mov 

ah, 3fh 

;  function  3FH  =  read  from  file  or  device 

int 

21h 

;  transfer  to  MS-DOS 

jc 

mainS 

;  error,  terminate 

cmp 

ax,  1 

;  any  character  read? 

jne 

main2 

;  end  of  file,  terminate  program 

call 

transit 

;  translate  character  if  necessary 

;  now  write  character  to  standard  output 

mov 

dx, offset 

DGROUP; char  ;  address  of  character 

mov 

cx,  1 

;  length  to  write  =  1 

mov 

bx, stdout 

;  handle  for  standard  output 

mov 

ah,40h 

;  function  40H  =  write  to  file  or  device 

int 

21h 

;  transfer  to  MS-DOS 

jc 

main3 

;  error,  terminate 

cmp 

ax,  1 

;  was  character  written? 

jne 

main3 

;  disk  full,  terminate  program 

jmp 

maini 

;  go  process  another  character 

Figure  14-5.  Assembly-language  source  code  for  the  LC filter  (file  LC.  ASM).  (more) 
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main? : 

mov 

int 

ax, 4c00h 

21h 

;  end  of  file  reached,  terminate 
;  program  with  return  code  =  0 

main3 : 

mov 

int 

ax, 4c01 h 

21h 

;  error  or  disk  full,  terminate 
;  program  with  return  code  =  1 

main 

endp 

;  end  of  main  procedure 

;  Translate  uppercase  {A-Z}  characters  to  corresponding 
;  lowercase  characters  {a-z}.  Leave  other  characters  unchanged. 


transit 

proc 

near 

cmp 

byte  ptr 

char, 'A' 

jb 

transx 

cmp 

byte  ptr 

char, 'Z' 

ja 

transx 

add 

byte  ptr 

char, 'a'-'A 

transx: 

ret 

transit 

endp 

-TEXT 

ends 

—DATA  segment  word  public  'DATA* 

char  db  0  ;  temporary  storage  for  input  character 

—DATA  ends 


STACK  segment  para  stack  'STACK' 
dw  64  dup  (?) 

STACK  ends 


end  main  ;  defines  program  entry  point 

Figure  14-5.  Continued. 


/* 


LC: 


a  simple  character-oriented  filter  to  translate 
all  uppercase  {A-Z}  to  lowercase  {a-z}  characters. 


Usage:  LC  [<  source]  [>  destination] 

Figure  14-6.  C  source  code for  the  LC filter  (file  LC.  C). 


(more) 


438  The  MS-DOS  Encyclopedia 


Article  14:  Writing  MS-DOS  Filters 


Ray  Duncan,  June  1987 


*/ 

#include  <stdio.h> 


main (argc, argv) 
int  argc; 
char  *argv[]; 

{  char  ch; 

while  (  (ch=getchar ( )  )  ! 

{  ch=translate (ch) ; 

putchar (ch) ; 

} 

exit  (0) ; 

} 

/* 

Translate  characters  A-Z  to  lowercase  equivalents 

*/ 

int  translate (ch) 
char  ch; 

{  if  (ch  >=  'A'  &&  ch  <=  ’Z’)  ch  +=  'a'-* A'; 

return  (ch) ; 

} 

Figure  14-6.  Continued. 

As  another  example,  Figure  14-7  contains  the  C  source  code  for  a  line-oriented  filter  called 
FIND.  This  simple  filter  is  invoked  with  a  command  line  in  the  form 

FIND  '^pattern"  <  source  >  destination 

FIND  searches  the  input  stream  for  lines  containing  the  pattern  specified  in  the  command 
line.  The  line  number  and  text  of  any  line  containing  a  match  is  sent  to  standard  output, 
with  any  tabs  expanded  to  eight-column  tab  stops. 

/* 

FIND.C  Searches  text  stream  for  a  string. 

Usage:  FIND  "pattern”  [<  source]  [>  destination] 

by  Ray  Duncan,  June  1987 


/*  read  a  character  */ 

=  EOF  ) 

/*  perform  any  necessary 
character  translation  */ 

/*  then  write  character  */ 

/*  terminate  at  end  of  file  */ 


*/ 

#include  <stdio.h> 

Figure  14-  7.  C  source  code  for  a  new  FIND  filter  (file  FIND.  C).  (more) 


Section  II:  Programming  in  the  MS-DOS  Environment  439 


Part  C:  Customizing  MS-DOS 


#define  TAB  '\x09' 

idefine  BLANK  '\x20' 

#define  TAB_WIDTH  8 

static  char  input [256]; 
static  char  output [256]; 
static  char  pattern [256] ; 

main (argc, argv) 
int  argc; 
char  *argv[]; 

{  int  line=0; 

if  (  argc  <  2  ) 

{  puts ("find:  missing 

exit ( 1 ) ; 


/*  ASCII  tab  character  (''I)  */ 

/*  ASCII  space  character  */ 

/*  columns  per  tab  stop  */ 

/*  buffer  for  line  from  input  */ 
/*  buffer  for  line  to  output  */ 
/*  buffer  for  search  pattern  */ 


/*  initialize  line  variable  */ 

/*  was  search  pattern  supplied?  */ 
pattern . " ) ; 

/*  abort  if  not  */ 


strcpy (pattern, argv [ 1 ] ) ; 

strupr (pattern)  ; 

while (  gets (input)  !=  NULL  ) 

{  line++; 

strcpy (output, input) ; 
strupr (input) ; 


/*  save  copy  of  string  to  find  */ 
/*  fold  it  to  uppercase  */ 

/*  read  a  line  from  input  */ 

/*  count  lines  */ 

/*  save  copy  of  input  string  */ 

/*  fold  input  to  uppercase  */ 

/*  if  line  contains  pattern  */ 


if(  strstr (input, pattern)  ) 

/*  write  it  to  standard  output  */ 
writeline (line, output) ; 


} 


exit  (0) ; 


/*  terminate  at  end  of  file  */ 


/* 

WRITELINE:  Write  line  number  and  text  to  standard  output, 
expanding  any  tab  characters  to  stops  defined  by  TAB_WIDTH. 

*/ 


writeline (line,p) 
int  line; 
char  *p; 


{ 


int  i=0; 
int  col=0; 

printf ("\n%4d:  ",line); 
while (  p[i]!=NULL  ) 

{  if (p[i]==TAB) 


/*  index  to  original  line  text  */ 

/*  actual  output  column  counter  */ 
/*  write  line  number  */ 

/*  while  end  of  line  not  reached  */ 
/*  if  current  char  =  tab,  expand  it 


{ 


do  putchar (BLANK) ; 
while ((++col  %  TAB_WIDTH) 


0); 


*/ 


} 

else  /*  otherwise  just  send  character  */ 

{  putchar (p[i] ) ; 

col++;  /*  count  columns  */ 

} 


Figure  14-7.  Continued. 
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i++; 


/*  advance  through  output  line  */ 


} 

Figure  14-7.  Continued. 

This  sample  FIND  filter  differs  from  the  FIND  filter  supplied  by  Microsoft  with  MS-DOS  in 
several  respects.  It  is  not  case  sensitive,  so  the  pattern  “foobar”  will  match  “FOOBAR”, 
“FooBar”,  and  so  forth.  Second,  this  filter  supports  no  switches;  these  are  left  as  an  ex¬ 
ercise  for  the  reader.  Third,  unlike  the  Microsoft  version  of  FIND,  this  program  always 
reads  from  standard  input;  it  is  not  able  to  open  its  own  files. 


Using  a  Filter  as  a  Child  Process 

Instead  of  incorporating  all  the  code  necessary  to  do  the  job  itself,  an  application  program 
can  load  and  execute  a  filter  as  a  child  process  to  carry  out  a  specific  task.  Before  the  child 
filter  is  loaded,  the  parent  must  arrange  for  the  standard  input  and  standard  output  handles 
that  will  be  inherited  by  the  child  to  be  attached  to  the  files  or  character  devices  that  will 
supply  the  filter’s  input  and  receive  its  output.  This  redirection  is  accomplished  with  the 
following  steps  using  Interrupt  21H  functions: 

1.  The  parent  process  uses  Function  45H  (Duplicate  File  Handle)  to  create  duplicates  of 
its  standard  input  and  standard  output  handles  and  then  saves  the  duplicates. 

2.  The  parent  opens  (with  Function  3DH)  or  creates  (with  Function  3CH)  the  files  or 
devices  that  the  child  process  will  use  for  input  and  output. 

3.  The  parent  uses  Function  46H  (Force  Duplicate  File  Handle)  to  force  its  own  standard 
device  handles  to  track  the  new  file  or  device  handles  acquired  in  step  2. 

4.  The  parent  uses  Function  4B00H  (Load  and  Execute  Program  [EXEC])  to  load  and 
execute  the  child  process.  The  child  inherits  the  redirected  standard  input  and  stan¬ 
dard  output  handles  and  uses  them  to  do  its  work.  The  parent  regains  control  after 
the  child  filter  terminates. 

5.  The  parent  uses  the  duplicate  handles  created  in  step  1,  together  with  Function  46H 
(Force  Duplicate  File  Handle),  to  restore  its  own  standard  input  and  standard  output 
handles  to  their  original  meanings. 

6.  The  parent  closes  (with  Function  3EH)  the  duplicate  handles  created  in  step  1, 
because  they  are  no  longer  needed. 

It  might  seem  as  though  the  parent  process  could  just  as  easily  close  its  own  standard  input 
and  standard  output  (handles  0  and  1),  open  the  input  and  output  files  needed  by  the  child, 
load  and  execute  the  child,  close  the  files  upon  regaining  control,  and  then  reopen  the 
CON  device  twice.  Because  the  open  operation  always  assigns  the  first  free  handle,  this 
approach  would  have  the  desired  effect  as  far  as  the  child  process  is  concerned.  However, 
it  would  throw  away  any  redirection  that  had  been  established  for  the  parent  process  by  its 
parent.  Thus,  the  need  to  preserve  any  preexisting  redirection  of  the  parent’s  standard 
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input  and  standard  output,  along  with  the  desire  to  preserve  the  parent’s  usual  output 
channel  for  informational  messages  right  up  to  the  actual  point  of  the  EXEC  call,  is  the 
reason  for  the  elaborate  procedure  outlined  above  in  steps  1  through  6. 

The  program  EXECSORT.ASM  in  Figure  14-8  demonstrates  this  redirection  of  input  and 
output  for  a  filter  run  as  a  child  process.  The  parent,  which  is  called  EXECSORT,  saves 
duplicates  of  its  current  standard  input  and  standard  output  handles  and  then  redirects 
those  handles  respectively  to  the  files  MYFILE.DAT  (which  it  opens)  and  MYFILE.SRT 
(which  it  creates).  EXECSORT  then  uses  Interrupt  21H  Function  4BH  (EXEC)  to  run  the 
SORT.EXE  filter  that  is  supplied  with  MS-DOS  (this  file  must  be  in  the  current  drive  and 
directory  for  the  demonstration  to  work  correctly). 

name  execsort 

title  'EXECSORT  -  demonstrate  EXEC  of  filter' 

.sail 

;  EXECSORT.ASM  -  demonstration  of  use  of  EXEC  to  run  the  SORT 

;  filter  as  a  child  process,  redirecting  its  input  and  output. 

;  This  program  requires  the  files  SORT.EXE  and  MYFILE.DAT  in 
;  the  current  drive  and  directory. 

;  Ray  Duncan,  June  1987 


stdin 

equ 

0 

;  standard  input 

stdout 

equ 

1 

;  standard  output 

stderr 

equ 

2 

;  standard  error 

stksize 

equ 

128 

;  size  of  stack 

cr 

equ 

Odh 

;  ASCII  carriage  return 

If 

equ 

Oah 

/  ASCII  linefeed 

jerr 

macro 

target 

;;  Macro  to  test  carry  flag 

local 

notset 

; ;  and  jump  if  flag  set. 

jnc 

notset 

;;  Uses  JMP  DISP16  to  avoid 

jmp 

target 

; ;  branch  out  of  range  errors 

notset : 

endm 

DGROUP 

group 

-DATA, -STACK 

;  'automatic  data  group' 

(more) 

Figure  14-8.  Assembly-language  source  code  demonstrating  use  of  a  filter  as  a  child  process.  This  code  redi¬ 
rects  the  standard  input  and  standard  output  handles  to files,  invokes  the  EXEC function  (Interrupt  21H  Func¬ 
tion  4BH)  to  run  the  SORT.EXE  program,  and  then  restores  the  original  meaning  of  the  standard  input  and 
standard  output  handles  (file  EXECSORT.ASM). 


442  The  MS-DOS  Encyclopedia 


Article  14;  Writing  MS-DOS  Filters 


_TEXT  segment  byte  public  'CODE'  ;  executable  code  segment 

assume  cs :_TEXT, ds : DGROUP, ss : -STACK 


stk—seg 

dw 

stk—ptr 

dw 

0 

main 

proc 

far 

mov 

ax, DGROUP 

mov 

ds,  ax 

mov 

ax,  es 

mov 

bx,  ss 

sub 

bx,  ax 

add 

bx, stksize/1 6 

mov 

ah, 4ah 

int 

21h 

jerr 

maini 

mov  bx,stdin 

mov  ah,45h 

int  21 h 

jerr  maini 

mov  oldin,ax 

mov  dx, offset  DGROUP : inf ile 

mov  ax,3d00h 

int  21h 

jerr  maini 

mov  bx,ax 

mov  cx,stdin 

mov  ah,46h 

int  21h 

jerr  maini 

mov  bx, stdout 

mov  ah,45h 

int  21h 

jerr  maini 

mov  oldout,ax 

mov  dx, offset  dGROUP routf il 


;  original  SS  contents 
;  original  SP  contents 

;  entry  point  from  MS-DOS 
;  set  DS  =  our  data  segment 

;  now  give  back  extra  memory  so 
;  child  SORT  has  somewhere  to  run... 
;  let  AX  =  segment  of  PSP  base 
;  and  BX  =  segment  of  stack  base 
;  reserve  seg  stack  -  seg  psp 
;  plus  paragraphs  of  stack 
;  fxn  4 AH  =  modify  memory  block 
;  transfer  to  MS-DOS 
;  jump  if  resize  block  failed 

;  prepare  stdin  and  stdout 
;  handles  for  child  SORT  process 

;  dup  the  handle  for  stdin 

;  transfer  to  MS-DOS 
;  jump  if  dup  failed 
;  save  dup'd  handle 

;  now  open  the  input  file 
;  mode  =  read-only 
;  transfer  to  MS-DOS 
;  jump  if  open  failed 

;  force  stdin  handle  to 
;  track  the  input  file  handle 

;  transfer  to  MS-DOS 
;  jump  if  force  dup  failed 

;  dup  the  handle  for  stdout 

;  transfer  to  MS-DOS 
;  jump  if  dup  failed 
;  save  dup'd  handle 

s  ;  now  create  the  output  file 


Figure  14-8.  Continued. 


( more) 
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mov 

cx,  0 

; 

normal  attribute 

mov 

ah, 3ch 

int 

21h 

; 

transfer  to  MS-DOS 

jerr 

maini 

jump  if  create  failed 

mov 

bx,  ax 

; 

force  stdout  handle  to 

mov 

cx, stdout 

; 

track  the  output  file  handle 

mov 

ah, 46h 

int 

21h 

f 

transfer  to  MS-DOS 

jerr 

maini 

r 

jump  if  force  dup  failed 

/ 

now  EXEC  the  child  SORT, 

; 

which  will  inherit  redirected 

' 

stdin  and  stdout  handles 

push 

ds 

; 

save  EXECSORT's  data  segment 

mov 

stk_seg, ss 

; 

save  EXECSORT's  stack  pointer 

mov 

stk_ptr, sp 

mov 

ax,  ds 

; 

set  ES  =  DS 

mov 

es,  ax 

mov 

dx, offset  DGROUP:cname 

DS:DX  =  child  pathname 

mov 

bx, offset  DGROUPipars 

EX:BX  =  parameter  block 

mov 

ax, 4b00h 

function  4BH,  subfunction  OOH 

int . 

21h 

transfer  to  MS-DOS 

cli 

; 

(for  bug  in  some  early  8088s) 

mov 

ss, stk_seg 

; 

restore  execsort's  stack  pointer 

mov 

sp, stk_ptr 

sti 

; 

(for  bug  in  some  early  8088s) 

pop 

ds 

restore  DS  =  our  data  segment 

jerr 

maini 

' 

jump  if  EXEC  failed 

mov 

bx, oldin 

; 

restore  original  meaning  of 

mov 

cx, stdin 

; 

standard  input  handle  for 

mov 

ah,46h 

; 

this  process 

int 

21h 

jerr 

maini 

jump  if  force  dup  failed 

mov 

bx, oldout 

restore  original  meaning 

mov 

cx, stdout 

of  standard  output  handle 

mov 

ah,46h 

for  this  process 

int 

21h 

jerr 

maini 

jump  if  force  dup  failed 

mov 

bx, oldin 

close  dup'd  handle  of 

mov 

ah, 3eh 

original  stdin 

int 

21h 

transfer  to  MS-DOS 

Figure  14-8.  Continued. 


(more) 
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jerr 

maini 

;  jump  if  close  failed 

mov 

bx, oldout 

;  close  dup'd  handle  of 

mov 

ah, 3eh 

;  original  stdout 

int 

21h 

;  transfer  to  MS-DOS 

jerr 

maini 

;  jump  if  close  failed 

;  display  success  message 

mov 

dx, offset  DGROUP:msg1 

;  address  of  message 

mov 

cx, msgl— len 

;  message  length 

mov 

bx, stdout 

;  handle  for  standard  output 

mov 

ah, 40h 

;  fxn  40H  =  write  file  or  device 

int 

jerr 

21h 

maini 

;  transfer  to  MS-DOS 

mov 

ax, 4c00h 

;  no  error,  terminate  program 

int 

21h 

;  with  return  code  =  0 

maini : 

mov 

ax, 4c01 h 

;  error,  terminate  program 

int 

21h 

;  with  return  code  =  1 

main 

-TEXT 

endp 

ends 

;  end  of  main  procedure 

-DATA 

segment 

para  public  *DATA* 

;  static  &  variable  data  segment 

infile 

db 

'MYFILE.DAT',0 

;  input  file  for  SORT  filter 

outfile 

db 

'MYFILE.SRT',0 

;  output  file  for  SORT  filter 

oldin 

dw 

7 

;  dup  of  old  stdin  handle 

oldout 

dw 

7 

;  dup  of  old  stdout  handle 

cname 

db 

' SORT, EXE ' ,  0 

;  pathname  of  child  SORT  process 

pars 

dw 

0 

;  segment  of  environment  block 
;  (0  =  inherit  parent's) 

dd 

tail 

;  long  address,  command  tail 

dd 

-1 

;  long  address,  default  FOB  #1 
;  (-1  =  none  supplied) 

dd 

-1 

;  long  address,  default  FOB  #2 
;  (-1  =  none  supplied) 

tail 

db 

0,  cr 

;  empty  command  tail  for  child 

msgl 

db 

cr, If, 'SORT  was  executed  as  child. ', cr, If 

msgl— len  equ 

—DATA  ends 

$-msg1 

Figure  14-8.  Continued. 
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—STACK  segment  para  stack  'STACK* 
db  stksize  dup  (?) 

—STACK  ends 


end  main  ;  defines  program  entry  point 

Figure  14-8.  Continued. 

The  MS-DOS  SORT  program  reads  the  file  MYFILE.DAT  via  its  standard  input  handle,  sorts 
the  file  alphabetically,  and  writes  the  sorted  data  to  MYFILE.SRT  via  its  standard  output 
handle.  When  SORT  terminates,  MS-DOS  closes  SORT’S  inherited  handles  for  standard  in¬ 
put  and  standard  output,  which  forces  an  update  of  the  directory  entries  for  the  associated 
files.  The  program  EXECSORT  then  resumes  execution,  restores  its  own  standard  input 
and  standard  output  handles  (which  are  still  open)  to  their  original  meanings,  displays  a 
success  message  on  standard  output,  and  exits  to  MS-DOS. 


Ray  Duncan 
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Article  15 

Installable  Device  Drivers 


The  software  that  runs  on  modern  computer  systems  is,  by  convention,  organized  into 
layers  with  varied  degrees  of  independence  from  the  underlying  computer  hardware.  The 
purpose  of  this  layering  is  threefold: 

•  To  minimize  the  impact  on  programs  of  differences  between  hardware  devices  or 
changes  in  the  hardware. 

•  To  allow  the  code  for  common  operations  to  be  centralized  and  optimized. 

•  To  ease  the  task  of  moving  programs  and  their  data  from  one  machine  to  another. 

The  top  and  most  hardware-independent  layer  is  usually  the  transient,  or  application, 
program,  which  performs  a  specific  job  and  deals  with  data  in  terms  of  files  and  records 
within  those  files.  Such  programs  are  called  transient  because  they  are  brought  into  RAM 
for  execution  when  needed  and  are  discarded  from  memory  when  their  job  is  finished. 
Examples  of  such  programs  are  Microsoft  Word,  various  programming  tools  such  as  the 
Microsoft  Macro  Assembler  (MASM)  and  the  Microsoft  Object  Linker  (LINK),  and  even 
some  of  the  standard  MS-DOS  utility  programs  such  as  CHKDSK  and  FORMAT. 

The  middle  layer  is  the  operating-system  kernel,  which  manages  the  allocation  of  system 
resources  such  as  memory  and  disk  storage,  provides  a  battery  of  services  to  application 
programs,  and  implements  disk  directories  and  the  other  housekeeping  details  of  disk 
storage.  The  MS-DOS  kernel  is  brought  into  memory  from  the  file  MSDOS.SYS  (or 
IBMDOS.COM  with  PC-DOS)  when  the  system  is  turned  on  or  restarted  and  remains  fixed 
in  memory  until  the  system  is  turned  off.  The  system’s  default  command  processor, 
COMMAND.COM,  and  system  manager  programs  such  as  Microsoft  Windows  bridge  the 
categories  of  application  program  and  operating  system:  Parts  of  them  remain  resident  in 
memory  at  all  times,  but  they  rely  on  the  MS-DOS  kernel  for  services  such  as  file  I/O.  See 
PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Structure  of  ms-dos:  Components 
of  MS-DOS. 

The  modules  in  the  lowest  layer  are  called  device  drivers.  These  drivers  are  the  com¬ 
ponents  of  the  operating  system  that  manage  the  controller,  or  adapter,  of  a  peripheral 
device — a  piece  of  hardware  that  the  computer  uses  for  such  purposes  as  storage  or  com¬ 
municating  with  the  outside  world.  Thus,  device  drivers  are  responsible  for  transferring 
data  between  a  peripheral  device  and  the  computer’s  RAM  memory,  where  other  pro¬ 
grams  can  work  on  it.  Drivers  shield  the  operating-system  kernel  from  the  need  to  deal 
with  hardware  I/O  port  addresses,  operating  characteristics,  and  the  peculiarities  of  a  par¬ 
ticular  peripheral  device,  just  as  the  kernel,  in  turn,  shields  application  programs  from 
the  details  of  file  management. 
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In  MS-DOS  versions  1.x,  device  drivers  were  integrated  into  the  operating  system  and 
could  be  extended  or  replaced  only  by  patching  the  files  that  contained  the  operating  sys¬ 
tem  itself.  Because  every  third-party  peripheral  manufacturer  evolved  a  different  method 
of  modifying  these  files  to  get  its  product  to  work,  conflicts  between  products  from  differ¬ 
ent  manufacturers  were  frequent  and  expansion  of  a  PC  with  new  disk  drives  and  other 
devices  (especially  fixed  disks)  was  often  a  chancy  proposition. 

In  MS-DOS  versions  2.0  and  later,  there  is  a  clean  separation  between  device  drivers  and 
the  MS-DOS  kernel.  Device  drivers  have  a  straightforward  structure  and  are  interfaced  to 
the  kernel  through  a  simple  and  clearly  defined  scheme  that  consists  of  far  calls,  function 
codes,  and  data  packets.  Given  adequate  information  about  the  hardware,  a  programmer 
can  write  a  new  device  driver  that  follows  this  structure  and  interface  for  almost  any  con¬ 
ceivable  peripheral  device;  such  a  driver  can  subsequently  be  installed  and  used  without 
any  changes  to  the  underlying  operating  system. 

This  article  explains  the  anatomy,  operation,  and  creation  of  drivers  for  MS-DOS  versions 
2.0  and  later.  Device  drivers  for  versions  1.x  are  not  discussed  further  here. 


Resident  and  Installable  Drivers 

Every  MS-DOS  system  contains  built-in  device  drivers  for  the  console  (keyboard  and  video 
display),  the  serial  port,  the  parallel  printer  port,  the  real-time  clock,  and  at  least  one  disk 
storage  device  (the  system  boot  device).  These  drivers,  known  as  the  resident  drivers,  are 
loaded  as  a  set  from  the  file  lO.SYS  (or  IBMBIO.COM  with  PC-DOS)  when  the  system  is 
turned  on  or  restarted. 

Drivers  for  additional  peripheral  devices  occupy  individual  files  on  the  disk.  These  drivers, 
called  installable  drivers,  are  loaded  and  linked  into  the  system  during  its  initialization  as 
a  result  of  DEVICE  directives  in  the  CONFIG.SYS  file.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Structure  of  ms-dos:  Components  of  MS-DOS.  Examples  of 
such  drivers  are  the  ANSI.SYS  and  RAMDISK.SYS  files  included  with  MS-DOS  version  3.2. 
In  all  other  respects,  installable  drivers  have  the  same  structure  and  relationship  to  the 
MS-DOS  kernel  as  the  resident  drivers.  All  drivers  in  the  system  are  chained  together  so 
that  MS-DOS  can  rapidly  search  the  entire  set  to  find  a  specific  block  or  character  device 
when  an  I/O  operation  is  requested. 

Device  drivers  as  a  whole  are  categorized  into  two  groups:  block-device  drivers  and 
character-device  drivers.  A  driver’s  membership  in  one  of  these  two  groups  determines 
how  the  associated  device  is  viewed  by  MS-DOS  and  what  functions  the  driver  itself  must 
support. 

Character-device  drivers 

Character-device  drivers  control  peripheral  devices,  such  as  a  terminal  or  a  printer,  that 
perform  input  and  output  one  character  (or  byte)  at  a  time.  Each  character-device  driver 
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ordinarily  supports  a  single  hardware  unit.  The  device  has  a  one-character  to  eight- 
character  logical  name  that  can  be  used  by  an  application  program  to  “open”  the  device 
for  input  or  output  as  though  it  were  a  file.  The  logical  name  is  strictly  a  means  of  identify¬ 
ing  the  driver  to  MS-DOS  and  has  no  physical  equivalent  on  the  device  (unlike  a  volume 
label  for  block  devices). 

The  three  resident  character-device  drivers  for  the  console,  serial  port,  and  printer  carry 
the  logical  device  names  CON,  AUX,  and  PRN,  respectively.  These  three  drivers  receive 
special  treatment  by  MS-DOS  that  allows  application  programs  to  address  the  associated 
devices  in  three  different  ways: 

•  They  can  be  opened  by  name  for  input  and  output  (like  any  other  character  device). 

•  They  are  supported  by  special-purpose  MS-DOS  function  calls  (Interrupt  21H  Func¬ 
tions  Ol-OCH). 

•  They  are  assigned  to  default  handles  (standard  input,  standard  output,  standard  error, 
standard  auxiliary,  and  standard  list)  that  need  not  be  opened  to  be  used. 

See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos: 
Character  Device  Input  and  Output. 

Other  character  devices  can  be  supported  by  simply  installing  additional  character-device 
drivers.  The  only  significant  restriction  on  the  total  number  of  devices  that  can  be  sup¬ 
ported,  other  than  the  memory  required  to  hold  the  drivers,  is  that  each  driver  must  have  a 
unique  logical  name.  When  MS-DOS  receives  an  open  request  for  a  character  device,  it 
searches  the  chain  of  device  drivers  in  order  from  the  last  driver  loaded  to  the  first.  Thus,  if 
more  than  one  driver  uses  the  same  logical  name,  the  last  driver  to  be  loaded  supersedes 
any  others  and  receives  all  I/O  requests  addressed  to  that  logical  name.  This  behavior  can 
be  used  to  advantage  in  some  situations.  For  example,  it  allows  the  more  powerful 
ANSI.SYS  display  driver  to  supersede  the  system’s  default  console  driver,  which  does  not 
support  cursor  positioning  and  character  attributes. 

The  MS-DOS  kernel’s  buffering  and  filtering  of  the  characters  that  pass  between  it  and 
a  character-device  driver  are  affected  by  whether  MS-DOS  regards  the  device  to  be  in 
cooked  mode  or  raw  mode.  During  cooked  mode  input,  MS-DOS  requests  characters  one 
at  a  time  from  the  driver  and  places  them  in  its  own  internal  buffer,  echoing  each  character 
to  the  screen  (if  the  input  device  is  the  keyboard)  and  checking  each  character  for  a 
Control-C  (03H)  or  a  Return  (ODH).  When  either  the  number  of  characters  requested  by 
the  application  program  has  been  received  or  a  Return  is  detected,  the  input  is  terminated 
and  the  data  is  copied  from  MS-DOS’s  internal  buffer  into  the  requesting  program’s  buffer. 
When  a  Control-C  is  detected,  MS-DOS  aborts  the  input  operation  and  transfers  to  the  rou¬ 
tine  whose  address  is  stored  in  the  Interrupt  23H  (Control-C  Handler  Address)  vector.  See 
PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Exception  Han¬ 
dlers.  Similarly,  during  output  in  cooked  mode,  MS-DOS  checks  between  each  character 
for  a  Control-C  pending  at  the  keyboard  and  aborts  the  output  operation  if  one  is  detected. 
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In  raw  mode,  the  exact  number  of  bytes  requested  by  the  application  program  is  read  or 
written,  without  regard  to  any  control  characters  such  as  Return  or  Control-C.  MS-DOS 
passes  the  entire  I/O  request  to  the  driver  in  a  single  operation,  instead  of  breaking  the 
request  into  single-character  reads  or  writes,  and  the  characters  are  transferred  directly  to 
or  from  the  requesting  program’s  buffer. 

The  mode  for  a  specific  device  can  be  queried  by  an  application  program  with  the  lOCTL 
Get  Device  Data  function  (Interrupt  21H  Function  44H  Subfunction  OOH);  the  mode  can  be 
selected  with  the  Set  Device  Data  function  (Interrupt  21H  Function  44H  Subfunction  OlH). 
See  SYSTEM  CALLS:  Interrupt  21h:  Function  44H.  The  driver  itself  is  not  usually  aware 
of  its  mode  and  the  mode  does  not  affect  its  operation. 

Block-Device  Drivers 

Block-device  drivers  control  peripheral  devices  that  transfer  data  in  chunks  rather  than  1 
byte  at  a  time.  Block  devices  are  usually  randomly  addressable  devices  such  as  floppy-  or 
fixed-disk  drives,  but  they  can  also  be  sequential  devices  such  as  magnetic-tape  drives.  A 
block  driver  can  support  more  than  one  physical  unit  and  can  also  map  two  or  more  logical 
units  onto  a  single  physical  unit,  as  with  a  partitioned  fixed  disk. 

MS-DOS  assigns  single-letter  drive  identifiers  (A,  B,  and  so  forth)  to  block  devices,  instead 
of  logical  names.  The  first  letter  assigned  to  a  block-device  driver  is  determined  solely  by 
the  driver’s  position  in  the  chain  of  all  drivers — that  is,  by  the  number  of  units  supported 
by  the  block  drivers  loaded  before  it;  the  total  number  of  letters  assigned  to  the  driver  is 
determined  by  the  number  of  logical  drive  units  the  driver  supports. 

MS-DOS  does  not  associate  a  mode  (cooked  or  raw)  with  block-device  drivers.  A  block- 
device  driver  always  reads  or  writes  exactly  the  number  of  sectors  requested  (barring  hard¬ 
ware  or  addressing  errors)  and  never  filters  or  otherwise  manipulates  the  contents  of  the 
blocks  being  transferred. 


structure  of  an  MS-DOS  Device  Driver 

A  device  driver  has  three  major  components  (Figure  15-1): 

•  The  device  header 

•  The  Strategy  routine  iStraf) 

•  The  Interrupt  routine  Qntf) 

The  device  header 

The  device  header  (Figure  15-2)  always  lies  at  the  beginning  of  the  driver.  It  contains  a  link 
to  the  next  driver  in  the  chain,  a  word  (l6  bits)  of  device  attribute  flags,  offsets  to  the  exe¬ 
cutable  Strategy  and  Interrupt  routines  for  the  device,  and  the  logical  device  name  if  it  is  a 
character  device  such  as  PRN  or  COMl  or  the  number  of  logical  units  if  it  is  a  block  device. 
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Interrupt  routine 

Initialization 

Media  Check 

Build  BPB 

lOCTL  Read  and  Write 

Status 

Read 

Write,  WriteA^erify 

Output  Until  Busy 

Flush  Buffers 

Device  Open 

Device  Close 

Check  if  Removable 

Generic  lOCTL 

Get/Set  Logical  Device 

Strategy  routine 

Device-driver  header 

Figure  15-1.  General  structure  of  an  MS-DOS  installable  device  driver 


Offset 

OOH 

02H 

04H 

06H 

OSH 

OAH 


12H 

Figure  15-2.  Device  header.  The  offsets  to  the  Strat  andlnix  routines  are  offsets  from  the  same  segment  used  to 
point  to  the  device  header. 

The  device  attribute  flags  word  (Table  15-1)  defines  whether  a  driver  controls  a  character 
or  a  block  device,  which  of  the  optional  subfunctions  added  in  MS-DOS  versions  3.0  and 
3.2  are  supported  by  the  driver,  and,  in  the  case  of  block  drivers,  whether  the  driver  sup¬ 
ports  IBM-compatible  disk  media.  The  least  significant  4  bits  of  the  device  attribute  flags 
word  control  whether  MS-DOS  should  use  the  driver  as  the  standard  input,  standard  out¬ 
put,  clock,  or  NUL  device;  each  of  these  4  bits  should  be  set  on  only  one  driver  in  the 
system  at  a  time. 


_ Link  to  next  driver,  offset _ 

Link  to  next  driver,  segment 
Device  attribute  word 
Offset,  Strategy  entry  point 
Offset,  Interrupt  entry  point 
Logical  name  (8  bytes)  if  character  device 
or 

Number  of  units  (1  byte)  followed  by 
7  bytes  of  reserved  space  if  block  device 


Section  II:  Programming  in  the  MS-DOS  Environment  45 1 


Part  C:  Customizing  MS-DOS 


Table  15-1.  Device  Attribute  Word  in  Device  Header. 


Bit  Setting 

15  *  1  if  character  device,  0  if  block  device 

14*  1  if  lOCTL  Read  and  Write  supported 

13  *  1  if  non-IBM  format  (block  device) 

1  if  Output  Until  Busy  supported  (character  device) 

12  0  (reserved) 

1 1  *  1  if  Open/Close/Removable  Media  supported  (versions  3.0  and  later) 

10  0  (reserved) 

9  0  (reserved) 

8  0  (reserved) 

7  0  (reserved) 

6*  1  if  Generic  lOCTL  and  Get/Set  Logical  Drive  supported  (version  3.2) 

5  0  (reserved) 

4  1  if  special  fast  output  function  for  CON  device  supported 

3  1  if  current  CLOCK  device 

2  1  if  current  NUL  device 

1  1  if  current  standard  output  istdout) 

0  1  if  current  standard  input  istdiri) 


*  Only  bits  6, 11,  and  13-15  have  significance  on  block  devices;  the  remainder  should  be  zero. 

The  information  in  the  device  header  is  ordinarily  used  only  by  the  MS-DOS  kernel  and 
is  not  available  to  application  programs.  However,  the  lOCTL  subfunctions  Get  and  Set 
Device  Data  (Interrupt  21H  Function  44H  Subfunctions  OOH  and  OlH)  can  be  used  to  in¬ 
spect  or  modify  some  of  the  bits  in  the  device  attribute  flags  word.  Note  that  there  is  not  a 
one-to-one  correspondence  between  the  bits  defined  for  those  functions  and  the  bits  in 
the  device  header.  For  example,  in  the  device  information  word  used  by  the  lOCTL  sub¬ 
functions,  bit  7  indicates  a  block  or  character  device;  in  the  device  attribute  word  of  the 
device  header,  bit  15  indicates  a  block  or  character  device. 

The  Strategy  routine  (^Strat) 

MS-DOS  calls  the  driver’s  Strategy  routine  as  the  first  step  of  any  operation,  passing  it  the 
segment  and  offset  of  a  data  structure  called  a  request  header  in  registers  ES:BX.  The  Strat¬ 
egy  routine  saves  this  pointer  for  subsequent  processing  by  the  Interrupt  routine  and 
returns  to  MS-DOS. 

A  request  header  is  essentially  a  small  buffer  used  for  private  communication  between 
MS-DOS  and  the  device  driver.  Both  MS-DOS  and  the  device  driver  read  and  write  infor¬ 
mation  in  the  request  header. 

The  first  13  bytes  of  a  request  header  are  the  same  for  all  device-driver  functions  and  are 
therefore  referred  to  as  the  static  portion  of  the  header.  The  number  and  contents  of  the 
subsequent  bytes  vary  according  to  the  type  of  operation  being  requested  by  the  MS-DOS 
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kernel  (Figure  15-3).  The  request  header’s  most  important  component  is  the  command 
code  passed  in  its  third  byte;  this  code  selects  a  driver  function  such  as  Read  or  Write. 
Other  information  passed  to  the  driver  in  the  request  header  includes  unit  numbers, 
transfer  addresses,  and  sector  or  byte  counts. 


OOH 

OlH 

02H 

OSH 

OSH 


ODH 

OEH 

lOH 

12H 

14H 


Request  header  length 

J 

Block-device  unit  number 

Command  code  (driver  subfunction) 

Returned  status 

Reserved 

Media  ID  byte 

\ 

Offset  of  data  to  be  transferred 

Segment  of  data  to  be  transferred 

Byte/sector  count 

Starting  sector  number 

Static  portion 
of  request  header 


Variable  portion 
of  request  header 


Figure  15-3  >  A  typical  driver  request  header.  The  bytes following  the  static  portion  are  the format  used for 
driver  Read,  Write,  Write  with  Verify,  lOCTLRead,  andlOCTL  Write  operations. 


The  Interrupt  routine  (/iitr) 

The  last  and  most  complex  part  of  a  device  driver  is  the  Interrupt  routine,  which  is  called 
by  MS-DOS  immediately  after  the  call  to  the  Strategy  routine.  The  bulk  of  the  Interrupt 
routine  is  a  collection  of  functions  or  subroutines,  sometimes  called  command-code  rou¬ 
tines,  that  carry  out  each  of  the  various  operations  the  MS-DOS  kernel  requires  a  driver  to 
support. 

When  the  Interrupt  routine  receives  control  from  MS-DOS,  it  saves  any  affected  registers, 
examines  the  request  header  whose  address  was  previously  passed  in  the  call  to  the  Strat¬ 
egy  routine,  determines  which  command-code  routine  is  needed,  and  branches  to  the 
appropriate  function.  When  the  operation  is  completed,  the  Interrupt  routine  stores  the 
status  (Table  15-2),  error  (Table  15-3),  and  any  other  applicable  information  into  the  re¬ 
quest  header,  restores  the  previous  contents  of  the  affected  registers,  and  returns  to  the 
MS-DOS  kernel. 
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Table  15-2.  The  Request  Header  Status  Word. 


Bits 

Meaning 

15 

Error 

12-14 

Reserved 

9 

Busy 

8 

Done 

0-7 

Error  code  if  bit  15  =  1 

Table  15-3.  Device-Driver  Error  Codes.* 


Code  Meaning 

OOH  Write-protect  violation 

OlH  Unknown  unit 

02H  Drive  not  ready 

03H  Unknown  command 

04H  CRC  error 

05H  Bad  drive  request  structure  length 

06H  Seek  error 

07H  Unknown  media 

OSH  Sector  not  found 

09H  Printer  out  of  paper 

OAH  Write  fault 

OBH  Read  fault 

OCH  General  failure 

ODH  Reserved 

OEH  Reserved 

OFH  Invalid  disk  change  (versions  3.x) 


•  Returned  in  bits  0-7  of  the  request  header  status  word. 

The  Interrupt  routine’s  name  is  misleading  in  that  it  is  never  entered  asynchronously  as  a 
hardware  interrupt.  The  division  of  function  between  the  Strategy  and  Interrupt  routines  is 
present  for  symmetry  with  UNDC/XENIX  and  MS  OS/2  drivers  but  is  essentially  meaning¬ 
less  in  single-tasking  MS-DOS  because  there  is  never  more  than  one  I/O  request  in 
progress  at  a  time. 

The  command-code  functions 

A  total  of  twenty  command  codes  are  defined  for  MS-DOS  device  drivers.  The  command 
codes  and  the  names  of  their  associated  Interrupt  routines  are  shown  in  the  following  list: 


454  The  MS-DOS  Encyclopedia 


Article  15:  Installable  Device  Drivers 


Code  Routine 

0  Init  (initialization) 

1  Media  Check  (block  devices  only) 

2  Build  BIOS  Parameter  Block  (block  devices  only) 

3  lOCTLRead 

4  Read  (Input) 

5  Nondestructive  Read  (character  devices  only) 

6  Input  Status  (character  devices  only) 

7  Flush  Input  Buffers  (character  devices  only) 

8  Write  (Output) 

9  Write  with  Verify 

10  Output  Status  (character  devices  only) 

1 1  Flush  Output  Buffers  (character  devices  only) 

12  lOCTL  Write 

13*  Device  Open 

14*  Device  Close 

1 5  *  Removable  Media  (block  devices  only) 

16  *  Output  Until  Busy  (character  devices  only) 

19 1  Generic  lOCTL  Request 

23 1  Get  Logical  Device  (block  devices  only) 

24t  Set  Logical  Device  (block  devices  only) 


*  MS-DOS  versions  3.0  and  later 
fMS-DOS  version  3.2 

Functions  0  through  12  must  be  supported  by  a  driver’s  Interrupt  section  under  all  versions 
of  MS-DOS.  Drivers  tailored  for  versions  3.0  and  3.1  can  optionally  support  an  additional  4 
functions  defined  under  those  versions  of  the  operating  system  and  drivers  designed  for 
version  3.2  can  support  3  more,  for  a  total  of  20.  MS-DOS  inspects  the  bits  in  the  device  at¬ 
tribute  word  of  the  device  header  to  determine  which  of  the  optional  version  3.x  functions 
a  driver  supports,  if  any. 

As  noted  in  the  list  above,  some  of  the  functions  are  relevant  only  for  character  drivers, 
some  only  for  block  drivers,  and  some  for  both.  In  any  case,  there  must  be  an  executable 
routine  present  for  each  function,  even  if  the  routine  does  nothing  but  set  the  done  flag  in 
the  status  word  of  the  request  header.  The  general  requirements  for  each  function  routine 
are  described  below. 

The  Init  function 

The  Init  (initialization)  function  (command  code  0)  for  a  driver  is  called  only  once,  when 
the  driver  is  loaded  (Figure  15-4).  Init  is  responsible  for  checking  that  the  hardware  device 
controlled  by  the  driver  is  present  and  functional,  performing  any  necessary  hardware  in¬ 
itialization  (such  as  a  reset  on  a  printer  or  a  seek  to  the  home  track  on  a  disk  device),  and 
capturing  any  interrupt  vectors  that  the  driver  will  need  later. 
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The  Init  function  is  passed  a  pointer  in  the  request  header  to  the  text  of  the  DEVICE  line 
in  CONFIG.SYS  that  caused  the  driver  to  be  loaded — specifically,  the  address  of  the  next 
byte  after  the  equal  sign  (=).  The  line  is  read-only  and  is  terminated  by  a  linefeed  or 
carriage-return  character;  it  can  be  scanned  by  the  driver  for  switches  or  other  parameters 
that  might  influence  the  driver’s  operation.  (Alphabetic  characters  in  the  line  are  folded  to 
uppercase.)  With  versions  3.0  and  later,  block  drivers  are  also  passed  the  drive  number 
that  will  be  assigned  to  their  first  unit  (0  =  A,  1  =  B,  and  so  on). 

Driver  called  with 

OOH 
OlH 
02H 
03H 

OSH 


ODH 

OEH 

lOH 

12H 

14H 

16H 


uun 

OlH 

02H 

03H 

OSH 


ODH 

OEH 

lOH 

12H 

14H 

16H 


Request  header  length 


Command  code 


Reserved 


Offset  of  C01SnFIG.SYS 
line  loading  driver  t 


Segment  of  CONFIG.SYS 
line  loading  driver  t 


First  unit  number  *t 


Dnver  returns 


Status 


Reserved 


Units  supported* 

Offset  of  free  memory 
above  driver 

Segment  of  free  memory 
above  driver 

Offset  of 

BPB  pointer  array* 

Segment  of 
BPB  pointer  array* 


*  Block-device  drivers  only 
t  Points  to  the  character  after  DEVICE= 
t  MS-DOS  3.0  and  later  only 

Figure  15-4.  Initialization  request  header  (command  code  0). 

When  it  returns  to  the  kernel,  the  Init  function  must  set  the  done  flag  in  the  status  word 
of  the  request  header  and  return  the  address  of  the  start  of  free  memory  after  the  driver 
(sometimes  called  the  break  address).  This  address  tells  the  kernel  where  it  can  build  cer¬ 
tain  control  structures  of  its  own  associated  with  the  driver  and  then  load  the  next  driver. 
The  Init  routine  of  a  block-device  driver  must  also  return  the  number  of  logical  units 
supported  by  the  driver  and  the  address  of  a  BPB  pointer  array. 

The  number  of  units  returned  by  a  block  driver  is  used  to  assign  device  identifiers.  For 
example,  if  at  the  time  the  driver  is  loaded  there  are  already  drivers  present  for  four  block 
devices  (drive  codes  0-3,  corresponding  to  drive  identifiers  A  through  D)  and  the  driver 
being  initialized  supports  four  units,  it  will  be  assigned  the  drive  numbers  4  through  7 
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(corresponding  to  the  drive  names  E  through  H).  (Although  there  is  also  a  field  in  the 
device  header  for  the  number  of  units,  it  is  not  inspected  by  MS-DOS;  rather,  it  is  set  by 
MS-DOS  from  the  information  returned  by  the  Init  function.) 

The  BPB  pointer  array  is  an  array  of  word  offsets  to  BIOS  parameter  blocks.  See  The  Build 
BIOS  Parameter  Block  Function  below;  PROGRAMMING  IN  THE  MS-DOS  ENVIRON¬ 
MENT:  Structure  of  ms-dos:  MS-DOS  Storage  Devices.  The  array  must  contain  one  entry 
for  each  unit  defined  by  the  driver,  although  all  entries  can  point  to  the  same  BPB  to  con¬ 
serve  memory.  During  the  operating-system  boot  sequence,  MS-DOS  scans  all  the  BPBs 
defined  by  all  the  units  in  all  the  resident  block-device  drivers  to  determine  the  largest 
sector  size  that  exists  on  any  device  in  the  system;  this  information  is  used  to  set  MS-DOS’s 
cache  buffer  size.  Thus,  the  sector  size  in  the  BPB  of  any  installable  block  driver  must  be 
no  larger  than  the  largest  sector  size  used  by  the  resident  block  drivers. 

If  the  Init  routine  finds  that  its  hardware  device  is  missing  or  defective,  it  can  bypass  the 
installation  of  the  driver  completely  by  returning  the  following  values  in  the  request 
header: 


Item  Value 

Number  of  units  0 

Address  of  free  memory  Segment  and  offset  of  the  driver’s  own  device  header 

A  character-device  driver  must  also  clear  bit  15  of  the  device  attribute  word  in  the  device 
header  so  that  MS-DOS  will  load  the  next  driver  in  the  same  location  as  the  one  that  just 
terminated  itself. 

The  operating-system  services  that  can  be  invoked  by  the  Init  routine  are  very  limited. 
Only  MS-DOS  Interrupt  21H  Functions  Ol-OCH  (various  character  input  and  output  ser¬ 
vices),  25H  (Set  Interrupt  Vector),  30H  (Get  MS-DOS  Version  Number),  and  35H  (Get  Inter¬ 
rupt  Vector)  can  be  called  by  the  Init  code.  These  functions  assist  the  driver  in  configuring 
itself  for  the  version  of  the  host  operating  system  it  is  to  run  under,  capturing  vectors  for 
hardware  interrupts,  and  displaying  informational  or  error  messages. 

The  amount  of  RAM  required  by  a  device  driver  can  be  reduced  by  positioning  the  Init 
routine  at  the  end  of  the  driver  and  returning  that  routine’s  starting  address  as  the  location 
of  the  first  free  memory. 

The  Media  Check  function 

The  Media  Check  function  (command  code  1)  is  used  only  in  block-device  drivers.  It  is 
called  by  the  MS-DOS  kernel  when  there  is  a  pending  drive  access  call  other  than  a  simple 
file  read  or  write  (for  example,  a  file  open,  close,  rename,  or  delete),  passing  the  media  ID 
byte  (Figure  15-5)  for  the  disk  that  MS-DOS  assumes  is  in  the  drive: 
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Description 

Medium 

0F9H 

5.25-inch  double-sided,  15  sectors 

OFCH 

5.25-inch  single-sided,  9  sectors 

OFDH 

5.25-inch  double-sided,  9  sectors 

OFEH 

5.25-inch  single-sided,  8  sectors 

OFFH 

5.25-inch  double-sided,  8  sectors 

0F9H 

3.5-inch  double-sided,  9  sectors 

OFOH 

3.5-inch  double-sided,  18  sectors 

0F8H 

Fixed  disk 

The  function  returns  a  code  indicating  whether  the  medium  has  been  changed  since  the 
last  transfer: 

Code  Meaning 

-1  Medium  changed 

0  Don’t  know  if  medium  changed 

1  Medium  not  changed 


Driver  called  with  Driver  returns 


*  MS-DOS  3.0  and  later  only 

Figure  15-5.  Media  Check  request  header  (command  code  1). 
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If  the  Media  Check  routine  asserts  that  the  disk  has  not  been  changed,  MS-DOS  bypasses 
rereading  the  FAT  and  proceeds  with  the  disk  access.  If  the  returned  code  indicates  that 
the  disk  has  been  changed,  MS-DOS  invalidates  all  buffers  associated  with  the  drive, 
including  buffers  containing  data  waiting  to  be  written  (this  data  is  simply  lost),  performs 
a  Build  BPB  call,  and  then  reads  the  disk’s  FAT  and  directory. 

The  action  taken  by  MS-DOS  when  Don't  know  is  returned  depends  on  the  state  of  its 
internal  buffers.  If  data  that  needs  to  be  written  out  is  present  in  the  buffers  associated  with 
the  drive,  MS-DOS  assumes  that  no  disk  change  has  occurred.  If  the  buffers  are  empty  or 
have  all  been  previously  flushed  to  the  disk,  MS-DOS  assumes  that  the  disk  was  changed 
and  proceeds  as  described  above  for  the  Medium  changed  return  code. 

If  bit  11  of  the  device  attribute  word  is  set  (that  is,  the  driver  supports  the  optional  Open/ 
Close/Removable  Media  functions),  the  host  system  is  MS-DOS  version  3.0  or  later,  and 
the  function  returns  the  Medium  changed  code  (-1),  the  function  must  also  return  the 
segment  and  offset  of  the  ASCIIZ  volume  label  for  the  previous  disk  in  the  drive.  (If 
the  driver  does  not  have  the  volume  label,  it  can  return  a  pointer  to  the  ASCIIZ  string 
NO  NAME^  If  MS-DOS  determines  that  the  disk  was  changed  with  unwritten  data  still 
present  in  the  buffers,  it  issues  a  critical  error  OFH  (Invalid  Disk  Change).  Application 
programs  can  trap  this  critical  error  and  prompt  the  user  to  replace  the  original  disk. 

In  character-device  drivers,  the  Media  Change  function  should  simply  set  the  done  flag  in 
the  status  word  of  the  request  header  and  return. 

The  Build  BIOS  Parameter  Block  function 

The  Build  BPB  function  (command  code  2)  is  supported  only  on  block  devices.  MS-DOS 
calls  this  function  when  the  Medium  changed  code  has  been  returned  by  the  Media 
Check  routine  or  when  the  Don  't  know  code  has  been  returned  and  there  are  no  dirty 
buffers  (buffers  that  have  not  yet  been  written  to  disk).  Thus,  a  call  to  this  function  indi¬ 
cates  that  the  disk  has  been  legally  changed. 

The  Build  BPB  call  receives  a  pointer  to  a  one-sector  buffer  in  the  request  header  (Figure 
15-6).  If  the  non-IBM-format  bit  (bit  13)  in  the  device  attribute  word  in  the  device  header  is 
zero,  the  buffer  contains  the  first  sector  of  the  disk’s  FAT,  with  the  media  ID  byte  in  the  first 
byte  of  the  buffer.  In  this  case,  the  contents  of  the  buffer  should  not  be  modified  by  the 
driver.  However,  if  the  non-IBM-format  bit  is  set,  the  buffer  can  be  used  by  the  driver  as 
scratch  space. 

The  Build  BPB  function  must  return  the  segment  and  offset  of  a  BIOS  parameter  block 
(Table  15-4)  for  the  disk  format  indicated  by  the  media  ID  byte  and  set  the  done  flag  in  the 
status  word  of  the  request  header.  The  information  in  the  BPB  is  used  by  the  kernel  to 
interpret  the  disk  structure  and  is  also  used  by  the  driver  itself  to  translate  logical  sector 
addresses  into  physical  track,  sector,  and  head  addresses.  If  bit  11  of  the  device  attribute 
word  is  set  (that  is,  the  driver  supports  the  optional  Open/Close/Removable  Media  func¬ 
tions)  and  the  host  system  is  MS-DOS  version  3.0  or  later,  this  routine  should  also  read  the 
volume  label  from  the  disk  and  save  it. 
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OOH 

OlH 

02H 

OSH 

05H 


ODH 

OEH 

lOH 

12H 

14H 


Driver  called  with  Driver  returns 


Request  header  length 

OOH 

OlH 

02H 

OSH 

Unit  number 

Command  code 

Status 

OSH 

Reserved 

ODH 

OEH 

Reserved 

Media  ID  byte 

Offset  of  FAT  buffer 

or  scratch  area 

lOH 

12H 

Segment  of  FAT  buffer 
or  scratch  area 

Offset  of  BIOS 
parameter  block 

14H 

Segment  of  BIOS 
parameter  block 

Figure  15-6.  Build  BPB  request  header  (command  code  2). 

Table  15-4,  Format  of  a  BIOS  Parameter  Block  (BPB). 


Bytes  Contents 


OO-OIH 

02H 

03-04H 

05H 

06-07H 

08-09H 

OAH 

OB-OCH 

OD-OEH 

OF-lOH 

11-12H 

13-14H 

15-18H 


Bytes  per  sector 

Sectors  per  allocation  unit  (must  be  power  of  2) 

Number  of  reserved  sectors  (starting  at  sector  0) 

Number  of  file  allocation  tables  (FATs) 

Maximum  number  of  root-directory  entries 
Total  number  of  sectors  in  medium 
Media  ID  byte 

Number  of  sectors  occupied  by  a  single  FAT 
Sectors  per  track  (versions  3.0  and  later) 

Number  of  heads  (versions  3.0  and  later) 

Number  of  hidden  sectors  (versions  3.0  and  later) 

High-order  word  of  number  of  hidden  sectors  (version  3.2) 

If  bytes  8-9  are  zero,  total  number  of  sectors  in  medium  (version  3.2) 


In  character-device  drivers,  the  Build  BPB  function  should  simply  set  the  done  flag  in  the 
status  word  of  the  request  header  and  return. 
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The  Read,  Write,  and  Write  with  Verify  functions 

The  Read  (Input)  function  (command  code  4)  transfers  data  from  the  device  into  a  speci¬ 
fied  memory  buffer.  The  Write  (Output)  function  (command  code  8)  transfers  data  from  a 
specified  memory  buffer  to  the  device.  The  Write  with  Verify  function  (command  code  9) 
works  like  the  Write  function  but,  if  feasible,  also  performs  a  read-after-write  verification 
that  the  data  was  transferred  correctly.  The  MS-DOS  kernel  calls  the  Write  with  Verify 
function,  instead  of  the  Write  function,  whenever  the  system’s  global  verify  flag  has 
been  turned  on  with  the  VERIFY  command  or  with  Interrupt  21H  Function  2EH  (Set 
Verify  Flag). 

All  three  of  these  driver  functions  are  called  by  the  MS-DOS  kernel  with  the  address  and 
length  of  the  buffer  for  the  data  to  be  transferred.  In  the  case  of  block-device  drivers,  the 
kernel  also  passes  the  drive  unit  code,  the  starting  logical  sector  number,  and  the  media 
ID  byte  for  the  disk  (Figure  15-7). 
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Figure  15-7.  The  request  header  for  lOCTL  Read  (command  code  3),  Read  (command  code  4),  Write  (com¬ 
mand  code  8),  Write  with  Verify  (command  code  9),  lOCTL  Write  (command  code  12),  and  Output  Until 
Busy  (command  code  16). 
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The  Read  and  Write  functions  must  perform  the  requested  I/O,  first  translating  each  logical 
sector  number  for  a  block  device  into  a  physical  track,  head,  and  sector  with  the  aid  of  the 
BIOS  parameter  block.  Then  the  functions  must  return  the  number  of  bytes  or  sectors 
actually  transferred  in  the  appropriate  field  of  the  request  header  and  also  set  the  done 
flag  in  the  request  header  status  word.  If  an  error  is  encountered  during  an  operation,  the 
functions  must  set  the  done  flag,  the  error  flag,  and  the  error  type  in  the  status  word  and 
also  report  the  number  of  bytes  or  sectors  successfully  transferred  before  the  error;  it  is  not 
sufficient  to  simply  report  the  error. 

Under  MS-DOS  versions  3.0  and  later,  the  Read  and  Write  functions  can  optionally  use  the 
reference  count  of  open  files  maintained  by  the  driver’s  Device  Open  and  Device  Close 
functions,  together  with  the  media  ID  byte,  to  determine  whether  the  medium  has  been 
illegally  changed.  If  the  medium  was  changed  with  files  open,  the  driver  can  return  the 
error  code  OFH  and  the  segment  and  offset  of  the  volume  label  for  the  correct  disk  so  that 
the  user  can  be  prompted  to  replace  the  disk. 

The  Nondestructive  Read  function 

The  Nondestructive  Read  function  (command  code  5)  is  supported  only  on  character 
devices.  It  allows  MS-DOS  to  look  ahead  in  the  character  stream  by  one  character  and  is 
used  to  check  for  Control-C  characters  pending  at  the  keyboard. 

The  function  is  called  by  the  kernel  with  no  parameters  other  than  the  command  code 
itself  (Figure  15-8).  It  must  set  the  done  bit  in  the  status  word  of  the  request  header  and 
also  set  the  busy  bit  in  the  status  word  to  reflect  whether  the  device’s  input  buffer  is  empty 
(busy  bit  =  1)  or  contains  at  least  one  character  (busy  bit  =  0).  If  the  latter,  the  function  must 
also  return  the  next  character  that  would  be  obtained  by  a  kernel  call  to  the  Read  function, 
without  removing  that  character  from  the  buffer  (hence  the  term  nondestructive). 

In  block-device  drivers,  the  Nondestructive  Read  function  should  simply  set  the  done  flag 
in  the  status  word  of  the  request  header  and  return. 
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Figure  15-8.  The  Nondestructive  Read  request  header. 
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The  Input  Status  and  Output  Status  functions 

The  Input  Status  and  Output  Status  functions  (command  codes  6  and  10)  are  defined  only 
for  character  devices.  They  are  called  with  no  parameters  in  the  request  header  other  than 
the  command  code  itself  and  return  their  results  in  the  busy  bit  of  the  request  header 
status  word  (Figure  15-9).  These  functions  constitute  the  driver-level  support  for  the  ser¬ 
vices  the  MS-DOS  kernel  provides  to  application  programs  by  means  of  Interrupt  21H 
Function  44H  Subfunctions  06H  and  07H  (Check  Input  Status  and  Check  Output  Status). 

MS-DOS  calls  the  Input  Status  function  to  determine  whether  there  are  characters  waiting 
in  a  type-ahead  buffer.  The  function  sets  the  done  bit  in  the  status  word  of  the  request 
header  and  sets  the  busy  bit  to  0  if  at  least  one  character  is  already  in  the  input  buffer  or  to 
1  if  no  characters  are  in  the  buffer  and  a  read  request  would  wait  on  a  character  from  the 
physical  device.  If  the  character  device  does  not  have  a  type-ahead  buffer,  the  Input  Status 
routine  should  always  return  the  busy  bit  set  to  0  so  that  MS-DOS  will  not  wait  for  some¬ 
thing  to  arrive  in  the  buffer  before  calling  the  Read  function. 
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Figure  15-9.  The  request  header  for  Input  Status  (command  code  6),  Flush  Input  Buffers  (command  code  7), 
Output  Status  (command  code  10),  and  Flush  Output  Buffers  (command  code  11). 

MS-DOS  uses  the  Output  Status  function  to  determine  whether  a  write  operation  is 
already  in  progress  for  the  device.  The  function  must  set  the  done  bit  and  the  busy  bit  (0 
if  the  device  is  idle  and  a  write  request  would  start  immediately;  1  if  a  write  is  already  in 
progress  and  a  new  write  request  would  be  delayed)  in  the  status  word  of  the  request 
header. 

In  block-device  drivers,  the  Input  Status  and  Output  Status  functions  should  simply  set  the 
done  flag  in  the  status  word  of  the  request  header  and  return. 

The  Flush  Input  Buffer  and  Flush  Output  Buffer  functions 

The  Flush  Input  Buffer  and  Flush  Output  Buffer  functions  (command  codes  7  and  11)  are 
defined  only  for  character  devices.  They  simply  terminate  any  read  (for  Flush  Input)  or 
write  (for  Flush  Output)  operations  that  are  in  progress  and  empty  the  associated  buffer. 
The  Flush  Input  Buffer  function  is  used  by  MS-DOS  to  discard  characters  waiting  in  the 
type-ahead  queue.  This  driver  action  corresponds  to  the  MS-DOS  service  provided  to 
application  programs  by  means  of  Interrupt  21H  Function  OCH  (Flush  Buffer,  Read 
Keyboard). 
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These  functions  are  called  with  no  parameters  in  the  request  header  other  than  the 
command  code  itself  Csee  Figure  15-9)  and  return  only  the  status  word. 

In  block-device  drivers,  the  Flush  Buffer  functions  have  no  meaning.  They  should  simply 
set  the  done  flag  in  the  status  word  of  the  request  header  and  return. 

The  lOCTL  Read  and  lOCTL  Write  functions 

The  lOCTL  (I/O  Control)  Read  and  lOCTL  Write  functions  (command  codes  3  and  12) 
allow  control  information  to  be  passed  directly  between  a  device  driver  and  an  application 
program.  The  lOCTL  Read  and  Write  driver  functions  are  called  by  the  MS-DOS  kernel 
only  if  the  lOCTL  flag  (bit  14)  is  set  in  the  device  attribute  word  of  the  device  header. 

The  MS-DOS  kernel  passes  the  address  and  length  of  the  buffer  that  contains  or  will 
receive  the  lOCTL  information  (see  Figure  15-7).  The  driver  must  return  the  actual  count 
of  bytes  transferred  and  set  the  done  flag  in  the  request  header  status  word.  Any  error 
code  returned  by  the  driver  is  ignored  by  the  kernel. 

lOCTL  Read  and  lOCTL  Write  operations  are  typically  used  to  configure  a  driver  or  device 
or  to  report  driver  or  device  status  and  do  not  usually  result  in  the  transfer  of  data  to  or 
from  the  physical  device.  These  functions  constitute  the  driver  support  for  the  services 
provided  to  application  programs  by  the  MS-DOS  kernel  through  Interrupt  21H  Function 
44H  Subfunctions  02H,  03H,  04H,  and  05H  (Receive  Control  Data  from  Character  Device, 
Send  Control  Data  to  Character  Device,  Receive  Control  Data  from  Block  Device,  and  Send 
Control  Data  to  Block  Device). 

The  Device  Open  and  Device  Close  functions 

The  Device  Open  and  Device  Close  functions  (command  codes  13  and  14)  are  supported 
only  in  MS-DOS  versions  3.0  and  later  and  are  called  only  if  the  open/close/removable 
media  flag  (bit  11)  is  set  in  the  device  attribute  word  of  the  device  header.  The  Device 
Open  and  Device  Close  functions  have  no  parameters  in  the  request  header  other  than  the 
unit  code  for  block  devices  and  return  nothing  except  the  done  flag  and,  if  applicable,  the 
error  flag  and  number  in  the  request  header  status  word  (Figure  15-10). 


*  Block-device  drivers  only 


Figure  15-10.  The  request  header  for  Device  Open  (command  code  13) >  Device  Close  (command  code  14),  and 
Removable  Media  (command  code  15). 
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Each  Interrupt  21H  request  by  an  application  to  open  or  create  a  file  or  to  open  a  character 
device  for  input  or  output  results  in  a  Device  Open  call  by  the  kernel  to  the  corresponding 
device  driver.  Similarly,  each  Interrupt  21H  call  by  an  application  to  close  a  file  or  device 
results  in  a  Device  Close  call  by  the  kernel  to  the  appropriate  device  driver.  These  Device 
Open  and  Device  Close  calls  are  in  addition  to  any  directory  read  or  write  calls  that  may 
be  necessary. 

On  block  devices,  the  Device  Open  and  Device  Close  functions  can  be  used  to  manage 
local  buffering  and  to  maintain  a  reference  count  of  the  number  of  open  files  on  a  device. 
Whenever  this  reference  count  is  decremented  to  zero,  all  files  on  the  disk  have  been 
closed  and  the  driver  should  flush  any  internal  buffers  so  that  data  is  not  lost,  as  the  user 
may  be  about  to  change  disks.  The  reference  count  can  also  be  used  together  with  the 
media  ID  byte  by  the  Read  and  Write  functions  to  determine  whether  the  disk  has  been 
changed  while  files  are  still  open. 

The  reference  count  should  be  forced  to  zero  when  a  Media  Check  call  that  returns  the 
Medium  changed  code  is  followed  by  a  Build  BPB  call,  to  provide  for  those  programs 
that  use  FCBs  to  open  files  and  then  never  close  them.  This  problem  does  not  arise  with 
programs  that  use  the  handle  functions  for  file  management,  because  all  handles  are 
always  closed  automatically  by  MS-DOS  on  behalf  of  the  program  when  it  terminates. 

See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  File 
and  Record  Management. 

On  character  devices,  the  Device  Open  and  Device  Close  functions  can  be  used  to  send 
hardware-dependent  initialization  and  post-I/O  strings  to  the  associated  device  (for  exam¬ 
ple,  a  reset  sequence  or  formfeed  character  to  precede  new  output  and  a  formfeed  to  fol¬ 
low  it).  Although  these  strings  can  be  written  directly  by  an  application  using  ordinary 
write  function  calls,  they  can  also  be  previously  passed  to  the  driver  by  application  pro¬ 
grams  with  lOCTL  Write  calls  (Interrupt  21H  Function  44H  Subfunction  05H),  which  in 
turn  are  translated  by  the  MS-DOS  kernel  into  driver  command  code  12  (lOCTL  Write) 
requests.  The  latter  method  makes  the  driver  responsible  for  sending  the  proper  control 
strings  to  the  device  each  time  a  Device  Open  or  Device  Close  is  executed,  but  this 
method  can  be  used  only  with  drivers  specifically  written  to  support  it. 

The  Removable  Media  function 

The  Removable  Media  function  (command  code  15)  is  defined  only  for  block  devices.  It 
is  supported  in  MS-DOS  versions  3.0  and  later  and  is  called  by  MS-DOS  only  if  the  open/ 
close/removable  media  flag  (bit  11)  is  set  in  the  device  attribute  word  of  the  device  header. 
This  function  constitutes  the  driver-level  support  for  the  service  provided  to  application 
programs  by  MS-DOS  by  means  of  Interrupt  21H  Function  44H  Subfunction  OSH  (Check  If 
Block  Device  Is  Removable). 

The  only  parameter  for  the  Removable  Media  function  is  the  unit  code  isee  Figure  15-10). 
The  function  sets  the  done  bit  in  the  request  header  status  word  and  sets  the  busy  bit  to  1  if 
the  disk  is  not  removable  or  to  0  if  the  disk  is  removable.  This  information  can  be  used  by 
MS-DOS  to  optimize  its  accesses  to  the  disk  and  to  eliminate  unnecessary  FAT  and  direc¬ 
tory  reads. 
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In  character-device  drivers,  the  Removable  Media  function  should  simply  set  the  done  flag 
in  the  status  word  of  the  request  header  and  return. 

The  Output  Until  Busy  function 

The  Output  Until  Busy  junction  (command  code  l6)  is  defined  only  for  character  devices 
under  MS-DOS  versions  3.0  and  later  and  is  called  by  the  MS-DOS  kernel  only  if  the  corre¬ 
sponding  flag  (bit  13)  is  set  in  the  device  attribute  word  of  the  device  header.  This  function 
is  an  optional  driver-optimization  function  included  specifically  for  the  benefit  of  back¬ 
ground  print  spoolers  driving  printers  that  have  internal  memory  buffers.  Such  printers  can 
accept  data  at  a  rapid  rate  until  the  buffer  is  full. 

The  Output  Until  Busy  function  is  called  with  the  address  and  length  of  the  data  to  be 
written  to  the  device  Csee  Figure  15-7).  It  transfers  data  continuously  to  the  device  until  the 
device  indicates  that  it  is  busy  or  until  the  data  is  exhausted.  The  function  then  must  set  the 
done  flag  in  the  request  header  status  word  and  return  the  actual  number  of  bytes  trans¬ 
ferred  in  the  appropriate  field  of  the  request  header. 

For  this  function  to  return  a  count  of  bytes  transferred  that  is  less  than  the  number  of  bytes 
requested  is  not  an  error.  MS-DOS  will  adjust  the  address  and  length  of  the  data  passed  in 
the  next  Output  Until  Busy  function  request  so  that  all  characters  are  sent. 

In  block-device  drivers,  the  Output  Until  Busy  function  should  simply  set  the  done  flag  in 
the  status  word  of  the  request  header  and  return. 

The  Genetic  lOCTL  function 

The  Generic  lOCTL  function  (command  code  19)  is  defined  under  MS-DOS  version  3.2 
and  is  called  only  if  the  3.2-functions-supported  flag  (bit  6)  is  set  in  the  device  attribute 
word  of  the  device  header.  This  driver  function  corresponds  to  the  MS-DOS  generic  lOCTL 
service  supplied  to  application  programs  by  means  of  Interrupt  21H  Function  44H  Sub¬ 
functions  OCH  (Generic  I/O  Control  for  Handles)  and  ODH  (Generic  I/O  Control  for  Block 
Devices). 

In  addition  to  the  usual  information  in  the  static  portion  of  the  request  header,  the  Generic 
lOCTL  function  is  passed  a  category  (major)  code,  a  function  (minor)  code,  the  contents 
of  the  SI  and  DI  registers  at  the  point  of  the  lOCTL  call,  and  the  segment  and  offset  of  a 
data  buffer  (Figure  15-11).  This  buffer  in  turn  contains  other  information  whose  format 
depends  on  the  major  and  minor  lOCTL  codes  passed  in  the  request  header.  The  driver 
must  interpret  the  major  and  minor  codes  in  the  request  header  and  the  contents  of  the  ad¬ 
ditional  buffer  to  determine  which  operation  it  will  carry  out  and  then  set  the  done  flag  in 
the  request  header  status  word  and  return  any  other  applicable  information  in  the  request 
header  or  the  data  buffer. 

Services  that  can  be  invoked  by  the  Generic  lOCTL  function,  if  the  driver  supports  them, 
include  configuring  the  driver  for  nonstandard  disk  formats,  reading  and  writing  entire 
disk  tracks  of  data,  and  formatting  and  verifying  tracks.  The  Generic  lOCTL  function  has 
been  designed  to  be  open-ended  so  that  it  can  be  used  to  easily  extend  the  device  driver 
definition  in  future  versions  of  MS-DOS. 
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*  Block-device  drivers  only 
Figure  15-11.  Generic  lOCTL  request  header. 

The  Get  Logical  Device  and  Set  Logical  Device  functions 

The  Get  and  Set  Logical  Device  functions  (command  codes  23  and  24)  are  defined  only  for 
block  devices  under  MS-DOS  version  3.2  and  are  called  only  if  the  3.2-functions-supported 
flag  (bit  6)  is  set  in  the  device  attribute  word  of  the  device  header.  They  correspond  to  the 
Get  and  Set  Logical  Drive  Map  services  supplied  by  MS-DOS  to  application  programs  by 
means  of  Interrupt  21H  Function  44H  Subfunctions  OEH  and  OFH. 

The  Get  and  Set  Logical  Device  functions  are  called  with  a  drive  unit  number  in  the 
request  header  (Figure  15-12).  Both  functions  return  a  status  word  for  the  operation  in  the 
request  header;  the  Get  Logical  Device  function  also  returns  a  unit  number. 

The  Get  Logical  Device  function  is  called  to  determine  whether  more  than  one  drive  letter 
is  assigned  to  the  same  physical  device.  It  returns  a  code  for  the  last  drive  letter  used  to  ref¬ 
erence  the  device  (1  =  A,  2  =  B,  and  so  on);  if  only  one  drive  letter  is  assigned  to  the  device, 
the  returned  unit  code  should  be  0. 

The  Set  Logical  Device  function  is  called  to  inform  the  driver  of  the  next  logical  drive  iden¬ 
tifier  that  will  be  used  to  reference  the  device.  The  unit  code  passed  by  the  MS-DOS  kernel 
in  this  case  is  zero  based  relative  to  the  logical  drives  supported  by  this  particular  driver. 
For  example,  if  the  driver  supports  two  logical  floppy-disk-drive  units  (A  and  B),  only  one 
physical  disk  drive  exists  in  the  system,  and  Set  Logical  Device  is  called  with  a  unit  number 
of  1,  the  driver  is  being  informed  that  the  next  read  or  write  request  from  the  MS-DOS 
kernel  will  be  directed  to  drive  B. 
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*  Get  Logical  Device  (Command  code  23)  only 
Figure  15-12.  Get  Logical  Device  and  Set  Logical  Device  request  header. 

In  character-device  drivers,  the  Get  Logical  Device  and  Set  Logical  Device  functions  should 
simply  set  the  done  flag  in  the  status  word  of  the  request  header  and  return. 


The  Processing  of  a  Typical  I/O  Request 

An  application  program  requests  an  I/O  operation  from  MS-DOS  by  loading  registers  with 
the  appropriate  values  and  addresses  and  executing  a  software  Interrupt  21H.  MS-DOS 
inspects  its  internal  tables,  searches  the  chain  of  device  headers  if  necessary,  and  deter¬ 
mines  which  device  driver  should  receive  the  I/O  request. 

MS-DOS  then  creates  a  request  header  data  packet  in  a  reserved  area  of  memory.  Disk  I/O 
requests  are  transformed  from  file  and  record  information  into  logical  sector  requests  by 
MS-DOS’s  interpretation  of  the  disk  directory  and  file  allocation  table.  (MS-DOS  locates 
these  disk  structures  using  the  information  returned  by  the  driver  from  a  previous  Build 
BPB  call  and  issues  additional  driver  read  requests,  if  necessary,  to  bring  their  sectors  into 
memory.) 

After  the  request  header  is  prepared,  MS-DOS  calls  the  device  driver’s  Strategy  entry  point, 
passing  the  address  of  the  request  header  in  registers  ES:BX.  The  Strategy  routine  saves  the 
address  of  the  request  header  and  performs  a  far  return  to  MS-DOS. 

MS-DOS  then  immediately  calls  the  device  driver’s  Interrupt  entry  point.  The  Interrupt 
routine  saves  all  registers,  retrieves  the  address  of  the  request  header  that  was  saved  by  the 
Strategy  routine,  extracts  the  command  code,  and  branches  to  the  appropriate  function  to 
perform  the  operation  requested  by  MS-DOS.  When  the  requested  function  is  complete, 
the  Interrupt  routine  sets  the  done  flag  in  the  status  word  and  places  any  other  required 
information  into  the  request  header,  restores  all  registers  to  their  state  at  entry,  and  per¬ 
forms  a  far  return. 
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Figure  15-13.  The  processing  of  a  typical  I/O  request from  an  application  program. 

MS-DOS  translates  the  driver’s  returned  status  into  the  appropriate  carry  flag  status, 
register  values,  and  (possibly)  error  code  for  the  MS-DOS  Interrupt  21H  function  that  was 
requested  and  returns  control  to  the  application  program.  Figure  15-13  sketches  this  entire 
flow  of  control  and  data. 

Note  that  a  single  Interrupt  21H  function  request  by  an  application  program  can  result  in 
many  operation  requests  by  MS-DOS  to  the  device  driver.  For  example,  if  the  application 
invokes  Interrupt  21H  Function  3DH  (Open  File  with  Handle)  to  open  a  file,  MS-DOS  may 
have  to  issue  multiple  sector  read  requests  to  the  driver  while  searching  the  directory  for 
the  filename.  Similarly,  an  application  program’s  request  to  write  a  string  to  the  screen  in 
cooked  mode  with  Interrupt  21H  Function  40H  (Write  File  or  Device)  will  result  in  a  write 
request  to  the  driver  for  each  character  in  the  string,  because  MS-DOS  filters  the  characters 
and  polls  the  keyboard  for  a  pending  Control-C  between  each  character  output. 


Writing  Device  Drivers 

Device  drivers  are  traditionally  coded  in  assembly  language,  both  because  of  the  rigid 
structural  requirements  and  because  of  the  need  to  keep  driver  execution  speed  high  and 
memory  overhead  low.  Although  MS-DOS  versions  3.0  and  later  are  capable  of  loading 
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drivers  in  .EXE  format,  versions  2.x  can  load  only  pure  memory-image  device  drivers  that 
do  not  require  relocation.  Therefore,  drivers  are  typically  written  as  though  they  were 
.COM  programs  with  an  “origin”  of  zero  and  converted  with  EXE2BIN  to  .BIN  or  .SYS  files 
so  that  they  will  be  compatible  with  any  version  of  MS-DOS  (2.0  or  later).  See  PROGRAM¬ 
MING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Structure  of  an 
Application  Program. 

The  device  header  must  be  located  at  the  beginning  of  the  file  (offset  0).  Both  words  in  the 
header’s  link  field  should  be  set  to  -1,  thus  allowing  MS-DOS  to  fix  up  the  link  field  when 
the  driver  is  loaded  during  system  initialization  so  that  it  points  to  the  next  driver  in  the 
chain.  When  a  single  file  contains  more  than  one  driver,  the  offset  portion  of  each  header 
link  field  should  point  to  the  next  header  in  that  file,  all  using  the  same  segment  base  of 
zero,  and  only  the  link  field  of  the  last  header  in  the  file  should  be  set  to  -1,  -1. 

The  device  attribute  word  must  reflect  the  device-driver  type  (character  or  block)  and  the 
bits  that  indicate  support  for  the  various  optional  command  codes  must  have  appropriate 
values.  The  device  header’s  offsets  to  the  Strategy  and  Interrupt  routines  must  be  relative 
to  the  same  segment  base  as  the  device  header  itself.  If  the  driver  is  for  a  character  device, 
the  name  field  should  be  filled  in  properly  with  the  device’s  logical  name,  which  can  be 
any  legal  eight-character  uppercase  filename  padded  with  spaces  and  without  a  colon. 
Duplication  of  existing  character-device  names  or  existing  disk-file  names  should  be 
avoided  (unless  a  resident  character-device  driver  is  being  intentionally  superseded). 

The  Strategy  and  Interrupt  routines  for  the  device  are  called  by  MS-DOS  by  means  of  an 
intersegment  call  (CALL  FAR)  and  must  return  to  MS-DOS  with  a  far  return.  Both  routines 
must  preserve  all  CPU  registers  and  flags.  The  MS-DOS  kernel’s  stack  has  room  for  40  to  50 
bytes  when  the  driver  is  called;  if  the  driver  makes  heavy  use  of  the  stack,  it  should  switch 
to  an  internal  stack  of  adequate  depth. 

The  Strategy  routine  is,  of  course,  very  simple.  It  need  only  save  the  address  of  the  request 
header  that  is  passed  to  it  in  registers  ES:BX  and  exit  back  to  the  kernel. 

The  logic  of  the  Interrupt  routine  is  necessarily  more  complex.  It  must  save  the  CPU  reg¬ 
isters  and  flags,  extract  the  command  code  from  the  request  header  whose  address  was 
previously  saved  by  the  Strategy  routine,  and  dispatch  the  appropriate  command-code 
function.  When  that  function  is  finished,  the  Interrupt  routine  must  ensure  that  the  appro¬ 
priate  status  and  other  information  is  placed  in  the  request  header,  restore  the  CPU  regis¬ 
ters  and  flags,  and  return  control  to  the  kernel. 

Although  the  interface  between  the  MS-DOS  kernel  and  the  command-code  routines  is 
fairly  simple,  it  is  also  strict.  The  command-code  functions  must  behave  exactly  as  they  are 
defined  or  the  system  will  behave  erratically.  Even  a  very  subtle  discrepancy  in  the  action 
of  a  driver  function  can  have  unexpectedly  large  global  effects.  For  example,  if  a  block 
driver  Read  function  returns  an  error  but  does  not  return  a  correct  value  for  the  number  of 
sectors  successfully  transferred,  the  MS-DOS  kernel  will  be  misled  in  its  attempts  to  retry 
the  read  for  only  the  failing  sectors  and  disk  data  might  be  corrupted. 
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Example  character  driver:  TEMPLATE 

Figure  15-14  contains  the  source  code  for  a  skeleton  character-device  driver  called 
TEMPLATE. ASM.  This  driver  does  nothing  except  display  a  sign-on  message  when  it  is 
loaded,  but  it  demonstrates  all  the  essential  driver  components,  including  the  device 
header.  Strategy  routine,  and  Interrupt  routine.  The  command-code  functions  take  no 
action  other  than  to  set  the  done  flag  in  the  request  header  status  word. 

name  template 

title  'TEMPLATE  -  installable  driver  template' 


;  TEMPLATE .ASM:  A  program  skeleton  for  an  installable 
;  device  driver  (MS-DOS  2.0  or  later) 

;  The  driver  command-code  routines  are  stubs  only  and  have 
;  no  effect  but  to  return  a  nonerror  "Done"  status. 

;  Ray  Duncan,  July  1 987 


_TEXT  segment  byte  public  'CODE' 

assume  cs :_TEXT, ds :_TEXT, es : NOTHING 


org  0 


MaxCmd 

equ 

24 

maximum  allowed  command  code 

12  for  MS-DOS  2.x 

16  for  MS-DOS  3. 0-3.1 

24  for  MS-DOS  3. 2-3. 3 

cr 

equ 

Odh 

ASCII  carriage  return 

If 

equ 

Oah 

ASCII  linefeed 

eom 

equ 

end-of-message  signal 

Header: 

dd 

-1 

device  driver  header 

link  to  next  device  driver 

dw 

0c840h 

device  attribute  word 

dw 

Strat  , 

"Strategy"  routine  entry  point 

dw 

Intr  , 

"Interrupt"  routine  entry  point 

db 

'TEMPLATE' 

logical  device  name 

RHPtr 

dd 

7 

?  pointer  to  request  header,  passed 
?  by  MS-DOS  kernel  to  Strategy  routine 

Figure  15-14. 

TEMPLATE.ASM,  the  source  file  for  the  TEMPLATE.SYS  driver. 

(more) 
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Dispatch: 


Strat 


Interrupt  routine  command-code 
dispatch  table 


dw 

Init 

0 

= 

initialize  driver 

dw 

MediaChk 

1 

= 

media  check  on  block  device 

dw 

BuildBPB 

2 

= 

build  BIOS  parameter  block 

dw 

loctlRd 

3 

= 

I/O  control  read 

dw 

Read 

4 

= 

read  (input)  from  device 

dw 

NdRead 

5 

= 

nondestructive  read 

dw 

InpStat 

6 

= 

return  current  input  status 

dw 

InpFlush 

7 

= 

flush  device  input  buffers 

dw 

Write 

8 

= 

write  (output)  to  device 

dw 

WriteVfy 

9 

= 

write  with  verify 

dw 

Out St at 

10 

= 

return  current  output  status 

dw 

OutFlush 

1 1 

= 

flush  output  buffers 

dw 

loctlWt 

12 

= 

I/O  control  write 

dw 

DevOpen 

13 

= 

device  open  (MS-DOS  3.0+) 

dw 

DevClose 

14 

= 

device  close  (MS-DOS  3.0+) 

dw 

RemMedia 

15 

= 

removable  media  (MS-DOS  3.0+) 

dw 

OutBusy 

16 

= 

output  until  busy  (MS-DOS  3.0+) 

dw 

Error 

17 

= 

not  used 

dw 

Error 

18 

= 

not  used 

dw 

GenlOCTL 

19 

= 

generic  lOCTL  (MS-DOS  3.2+) 

dw 

Error 

20 

= 

not  used 

dw 

Error 

21 

= 

not  used 

dw 

Error 

22 

= 

not  used 

dw 

GetLogDev 

23 

= 

get  logical  device  (MS-DOS  3.2+) 

dw 

SetLogDev 

24 

= 

set  logical  device  (MS-DOS  3.2+) 

proc 

far  ; 

device  driver  Strategy  routine, 

called  by  MS-DOS  kernel  with 
ES:BX  =  address  of  request  header 


;  save  pointer  to  request  header 
mov  word  ptr  cs : [RHPtr  ] ,  bx 

mov  word  ptr  cs : [RHPtr+2] , es 


ret 

Strat  endp 


Intr  proc  far 


push  ax 

push  bx 

push  cx 

push  dx 

push  ds 

Figure  15-14.  Continued. 


;  back  to  MS-DOS  kernel 


;  device  driver  Interrupt  routine, 

;  called  by  MS-DOS  kernel  immediately 
;  after  call  to  Strategy  routine 

;  save  general  registers 


(more) 
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Intrl  : 


Intr2 ; 


push 

es 

push 

di 

push 

si 

push 

bp 

push 

cs 

;  make  local  data  addressable 

pop 

ds 

;  by  setting  DS  =  CS 

les 

di,  [RHPtr  ] 

;  let  ES:DI  =  request  header 

;  get  BX  =  command  code 

mov 

bl,es: [di+2] 

xor 

bh,bh 

cmp 

bx , MaxCmd 

;  make  sure  it's  valid 

jle 

Intrl 

;  jump,  function  code  is  ok 

call 

Error 

;  set  error  bit,  ’’Unknown  Command”  code 

jmp 

Intr2 

shl 

bx,  1 

;  form  index  to  dispatch  table 
;  and  branch  to  command-code  routine 

call 

word  ptr  [bx+Dispatch] 

les 

di,  [RHPtr  ] 

;  ES:DI  =  address  of  request  header 

or 

ax, 01 OOh 

;  merge  Done  bit  into  status  and 

mov 

es : [di+3] , ax 

;  store  status  into  request  header 

pop 

bp 

;  restore  general  registers 

pop 

si 

pop 

di 

pop 

es 

pop 

ds 

pop 

dx 

pop 

cx 

pop 

bx 

pop 

ax 

ret 

;  return  to  MS-DOS  kernel 

;  Command-code  routines  are  called  by  the  Interrupt  routine 
;  via  the  dispatch  table  with  ES:DI  pointing  to  the  request 
;  header.  Each  routine  should  return  AX  =  OOH  if  function  was 
;  completed  successfully  or  AX  =  8000H  +  error  code  if 
;  function  failed. 


MediaChk  proc  near  ;  function  1  =  Media  Check 

xor  ax, ax 

ret 

MediaChk  endp 

Figure  15-14.  Continued. 


(more) 
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BuildBPB  proc  near  ;  function  2  =  Build  BPB 

xor  ax, ax 

ret 

BuildBPB  endp 


loctlRd 

proc 

near 

;  function 

3  =  I/O  Control  Read 

xor 

ret 

ax,  ax 

loctlRd 

endp 

Read 

proc 

near 

;  function 

4  =  Read  (Input) 

xor 

ret 

ax,  ax 

Read 

endp 

NdRead 

proc 

near 

;  function 

5  =  Nondestructive  Read 

xor 

ret 

ax,  ax 

NdRead 

endp 

InpStat 

proc 

near 

;  function 

6  =  Input  Status 

xor 

ret 

ax,  ax 

InpStat 

endp 

InpFlush  proc 

near 

;  function 

7  =  Flush  Input  Buffers 

xor 

ax,  ax 

ret 

InpFlush  endp 
Figure  15-14.  Continued. 


(more) 
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Write  proc  near  ;  function  8  =  Write  (Output) 

xor  ax, ax 

ret 

Write  endp 

WriteVfy  proc  near  ;  function  9  =  Write  with  Verify 

xor  ax, ax 

ret 

WriteVfy  endp 

OutStat  proc  near  ;  function  10  =  Output  Status 

xor  ax, ax 

ret 

OutStat  endp 

OutFlush  proc  near  ;  function  1 1  =  Flush  Output  Buffers 

xor  ax, ax 

ret 

OutFlush  endp 

loctlWt  proc  near  ;  function  12  =  I/O  Control  Write 

xor  ax, ax 

ret 

loctlWt  endp 

DevOpen  proc  near  ;  function  13=  Device  Open 

xor  ax, ax 

ret 

DevOpen  endp 

Figure  15-14.  Continued.  (more) 
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DevClose  proc  near 

xor  ax, ax 

ret 

DevClose  endp 


RemMedia  proc  near 

xor  ax, ax 
ret 

RemMedia  endp 


OutBusy  proc  near 

xor  ax, ax 

ret 

OutBusy  endp 


GenlOCTL  proc  near 

xor  ax, ax 
ret 

GenlOCTL  endp 


GetLogDev  proc  near 

xor  ax, ax 

ret 

GetLogDev  endp 


SetLogDev  proc  near 

xor  ax, ax 
ret 

SetLogDev  endp 

Figure  15-14.  Continued. 


;  function  14=  Device  Close 


;  function  15  =  Removable  Media 


;  function  1 6  =  Output  Until  Busy 


;  function  1 9  =  Generic  lOCTL 


;  function  23  =  Get  Logical  Device 


;  function  24  =  Set  Logical  Device 


(more) 
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Error 

proc 

near 

;  bad  command  code  in  request  header 

mov 

ax, 8003h 

;  error  bit  +  "Unknown  Command"  code 

ret 

Error 

endp 

Init 

proc 

near 

;  function  0  =  initialize  driver 

push 

es 

;  save  address  of  request  header 

push 

di 

mov 

ah,  9 

;  display  driver  sign-on  message 

mov 

dx, offset 

Ident 

int 

21h 

pop 

di 

;  restore  request  header  address 

pop 

es 

;  set  address  of  free  memory 

;  above  driver  (break  address) 

mov 

word  ptr  < 

es : [di+1 4] , offset  Init 

mov 

word  ptr  < 

es : [di+1 6] , cs 

xor 

ax,  ax 

;  return  status 

ret 

Init 

endp 

Ident 

db 

cr,lf,lf 

db 

’ TEMPLATE 

Example  Device  Driver' 

db 

cr, If, eom 

Intr 

endp 

-TEXT 

ends 

end 

Figure  15-14.  Continued. 


TEMPLATE.ASM  can  be  assembled,  linked,  and  converted  into  a  loadable  driver  with  the 
following  commands: 

OMASM  TEMPLATE;  <Enter> 

OLINK  TEMPLATE;  <Enter> 

OEXE2BIN  TEMPLATE.EXE  TEMPLATE. SYS  <Enter> 

The  Microsoft  Object  Linker  (LINK)  will  display  the  warning  message  No  Stack  Segment, 
this  message  can  be  ignored.  The  driver  can  then  be  installed  by  adding  the  line 

DEVICE=TEMPLATE . SYS 


Section  II:  Programming  in  the  MS-DOS  Environment  477 


Part  C:  Customizing  MS-DOS 


to  the  CONFIG.SYS  file  and  restarting  the  system.  The  fact  that  the  TEMPLATE.SYS 
driver  also  has  the  logical  character-device  name  TEMPLATE  allows  the  demonstration  of 
an  interesting  MS-DOS  effect:  After  the  driver  is  installed,  the  file  that  contains  it  can  no 
longer  be  copied,  renamed,  or  deleted.  The  reason  for  this  limitation  is  that  MS-DOS 
always  searches  its  list  of  character-device  names  first  when  an  open  request  is  issued, 
before  it  inspects  the  disk  directory.  The  only  way  to  erase  the  TEMPLATE.SYS  file  is  to 
modify  the  CONFIG.SYS  file  to  remove  the  associated  DEVICE  statement  and  then  restart 
the  system. 

For  a  complete  example  of  a  character-device  driver  for  interrupt-driven  serial  communica¬ 
tions,  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos: 
Interrupt-Driven  Communications. 

Example  block  driver;  TINYDISK 

Figure  15-15  contains  the  source  code  for  a  simple  64  KB  virtual  disk  (RAMdisk)  called 
TINYDISK.ASM.  This  code  provides  a  working  example  of  a  simple  block-device  driver. 
When  its  Initialization  routine  is  called  by  the  kernel,  TINYDISK  allocates  itself  64  KB  of 
RAM  and  maps  a  disk  structure  onto  the  RAM  in  the  form  of  a  boot  sector  containing  a 
valid  BPB,  a  FAT,  a  root  directory,  and  a  files  area.  See  PROGRAMMING  IN  THE  MS-DOS 
ENVIRONMENT:  Structure  of  ms-dos:  MS-DOS  Storage  Devices. 

name  tinydisk 

title  TINYDISK  example  block-device  driver 
;  TINYDISK.ASM  —  64  KB  RAMdisk 
;  Ray  Duncan,  July  1987 

;  Example  of  a  simple  installable  block-device  driver. 


-TEXT 

segment 

public  'CODE 

assume 

cs  :_TEXT,  ds 

-TEXT,  es: -TEXT 

org 

0 

MaxCmd 

equ 

12 

;  max  driver  command  code 

;  (no  MS-DOS  3.x  functions) 

cr 

equ 

Odh 

;  ASCII  carriage  return 

If 

equ 

Oah 

;  ASCII  linefeed 

blank 

equ 

020h 

;  ASCII  space  code 

eom 

equ 

;  end-of-message  signal 

Secsize 

equ 

512 

;  bytes/sector,  IBM- compatible  media 

Figure  15-15.  TINYDISK.ASM,  the  source  file  for  the  TINYDISKSYS  driver.  (more) 
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device-driver  header 


Header 

dd 

-1 

/ 

link  to  next  driver  in  chain 

dw 

0 

i 

device  attribute  word 

dw 

Strat 

"Strategy"  routine  entry  point 

dw 

Intr 

"Interrupt"  routine  entry  point 

db 

1 

9 

number  of  units,  this  device 

db 

7  dup  (0) 

9 

reserved  area  (block-device  drivers) 

RHPtr 

dd 

7 

segment : of f set  of  request  header 

Secseg 

dw 

? 

segment  base  of  sector  storage 

Xfrsec 

dw 

0 

9 

current  sector  for  transfer 

Xfrcnt 

dw 

0 

9 

sectors  successfully  transferred 

Xfrreq 

dw 

0 

9 

number  of  sectors  requested 

Xfraddr 

dd 

0 

9 

working  address  for  transfer 

Array 

dw 

BPB 

; 

array  of  pointers  to  BPB 

;  for  each  supported  unit 


Bootrec  equ 

$ 

jmp 

$ 

;  phony  JMP  at  start  of 

nop 

;  boot  sector;  this  field 

;  must  be  3  bytes 

db 

'MS  2.0' 

;  OEM  identity  field 

;  BIOS  Parameter  Block  (BPB) 

BPB  dw 

Secsize 

;  OOH  -  bytes  per  sector 

db 

1 

;  02H  -  sectors  per  cluster 

dw 

1 

;  03H  -  reserved  sectors 

db 

1 

;  OSH  -  number  of  FATs 

dw 

32 

;  06H  -  root  directory  entries 

dw 

128 

;  08H  -  sectors  =  64  KB/secsize 

db 

0f8h 

;  OAH  -  media  descriptor 

dw 

1 

;  OBH  -  sectors  per  FAT 

Bootrec_len 

equ  $-Bootrec 

Strat 

proc 

far  ;  RAMdisk 

strategy  routine 

;  save  address  of  request  header 

mov 

word  ptr  cs: RHPtr, bx 

mov 

word  ptr  cs : [RHPtr+2 ] , es 

ret 

;  back  to 

MS-DOS  kernel 

Strat  endp 

Figure  15-15.  Continued. 


(more) 
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Intr 

proc 

far 

;  RAMdisk  interrupt  routine 

push 

ax 

;  save  general  registers 

push 

bx 

push 

cx 

push 

dx 

push 

ds 

push 

es 

push 

di 

push 

si 

push 

bp 

mov 

ax,  cs 

;  make  local  data  addressable 

mov 

ds,  ax 

les 

di, (RHPtr  ] 

;  ES:DI  =  request  header 

mov 

bl,es: [di+2] 

;  get  command  code 

xor 

bh,bh 

cmp 

bx, MaxCmd 

;  make  sure  it's  valid 

jle 

Intrl 

;  jump,  function  code  is  ok 

mov 

ax, 8003h 

;  set  Error  bit  and 

jmp 

Intr3 

;  "Unknown  Command”  error  code 

Intrl  : 

shl 

bx,  1 

;  form  index  to  dispatch  table  and 
;  branch  to  command-code  routine 

call 

word  ptr  [bx+Dispatch] 

;  should  return  AX  =  status 

les 

di,  [RHPtr  ] 

;  restore  ES:DI  =  request  header 

Intr3 : 

or 

ax, 01 OOh 

;  merge  Done  bit  into  status  and  store 

mov 

es : [di+3] , ax 

;  status  into  request  header 

Intr4: 

pop 

bp 

;  restore  general  registers 

pop 

si 

pop 

di 

pop 

es 

pop 

ds 

pop 

dx 

pop 

cx 

pop 

bx 

pop 

ax 

ret 

;  return  to  MS-DOS  kernel 

Intr 

endp 

Figure  15-15.  Continued. 


(more) 
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Dispatch: 

command-code  dispatch  table 
all  command-code  routines  are 
entered  with  ES:DI  pointing 
to  request  header  and  return 
the  operation  status  in  AX 

dw 

Init 

0  =  initialize  driver 

dw 

MediaChk 

1  =  media  check  on  block  device 

dw 

BuildBPB 

2  =  build  BIOS  parameter  block  d 

dw 

Dummy 

3  =  I/O  control  read 

dw 

Read 

4  =  read  (input)  from  device 

dw 

Dummy 

5  =  nondestructive  read 

dw 

Dummy 

6  =  return  current  input  status 

dw 

Dummy 

7  =  flush  device  input  buffers 

dw 

Write 

8  =  write  (output)  to  device 

dw 

Write 

9  =  write  with  verify 

dw 

Dummy 

10  =  return  current  output  status 

dw 

Dummy 

11  =  flush  output  buffers 

dw 

Dummy 

12  =  I/O  control  write 

MediaChk  proc 

near 

;  command 

code 

:  1  =  Media  Check 

;  return  ' 

"not 

changed”  code 

mov 

byte  ptr  es: 

[di+Oeh] , 1 

xor 

ax,  ax 

;  and  success 

status 

ret 

MediaChk  endp 

BuildBPB  proc 

near 

;  command  code  2  = 

'  Build  BPB 

mov 

mov 

xor 

ret 

word  ptr  es: 
word  ptr  es; 

ax,  ax 

;  put  BPB  address  in  request  header 
:  [di+12h] , offset  BPB 
;  [di+1 4h] , cs 

;  return  success  status 

BuildBPB  endp 

Read 

proc 

near 

;  command  code  4  = 

^  Read  (Input) 

call 

Setup 

;  set  up  transfer 

variables 

Readi : 

mov 

cmp 

je 

mov 

call 

ax, Xfrcnt 
ax, Xfrreq 
Read2 

ax, Xf rsec 
Mapsec 

;  done  with  all  sectors  yet? 

;  jump  if  transfer  completed 
;  get  next  sector  number 
;  and  map  it 

Figure  15-15.  Continued. 
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mov 

ax,  es 

mov 

si,  di 

les 

di,Xfraddr 

mov 

ds,  ax 

mov 

cx, Secsize 

cld 

rep  movsb 

pu§h 

cs 

pop 

ds 

inc 

Xfrsec 

add 

word  ptr  Xfraddr 

inc 

Xfrcnt 

jmp 

Readi 

ES:DI  =  requester's  buffer 
DS:SI  =  RAMdisk  address 
transfer  logical  sector  from 
RAMdisk  to  requestor 

restore  local  addressing 

advance  sector  number 
advance  transfer  address 
Secsize 

count  sectors  transferred 


Read2 : 

xor  ax, ax 

les  di,RHPtr 

mov  bx,Xfrcnt 

mov  es : [di+1 2h] ,bx 

ret 

Read  endp 


;  all  sectors  transferred 
;  return  success  status 
;  put  actual  transfer  count 
;  into  request  header 


Write 


Writel 


proc 

near  ; 

command  code  8  =  Write  (Output) 
command  code  9  =  Write  with  Verify 

call 

Setup  / 

set  up  transfer  variables 

mov 

ax, Xfrcnt  ; 

done  with  all  sectors  yet? 

cmp 

ax, Xfrreq 

je 

Write2 

jump  if  transfer  completed 

mov 

ax, Xfrsec  ; 

get  next  sector  number 

call 

Mapsec  ; 

and  map  it 

Ids 

si, Xfraddr 

mov 

cx, Secsize  ; 

transfer  logical  sector  from 

cld 

; 

requester  to  RAMdisk 

rep  movsb 

push 

cs  ; 

restore  local  addressing 

pop 

ds 

inc 

Xfrsec  ; 

advance  sector  number 

advance  transfer  address 

add 

word  ptr  Xfraddr, 

Secsize 

inc 

Xfrcnt  ; 

count  sectors  transferred 

jmp 

Writel 

Write2 : 

xor  ax, ax 

les  di,RHPtr 


all  sectors  transferred 
return  success  status 
put  actual  transfer  count 


Figure  15-15.  Continued. 
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mov 

mov 

ret 

bx, Xfrcnt 

es : [di+1 2h] , bx 

;  into  request  header 

Write 

endp 

Dummy 

proc 

near 

;  called  for  unsupported  functions  • 

xor 

ret 

ax,  ax 

;  return  success  flag  for  all 

Dummy 

endp 

Mapsec 

proc 

near 

;  map  sector  number  to  memory  address 
;  call  with  AX  =  logical  sector  no. 

;  return  ES:DI  =  memory  address 

mov 

mul 

add 

mov 

xor 

ret 

di,  Secsize/1 6 
di 

ax, Secseg 

es,  ax 

di,  di 

;  paragraphs  per  sector 

;  ♦  logical  sector  number 

;  +  segment  base  of  sector  storage 

;  now  ES:DI  points  to  sector 

Mapsec 

endp 

Setup 

proc 

near 

;  set  up  for  read  or  write 

push 

push 

mov 

mov 

mov 

mov 

les 

mov 

mov 

mov 

pop 

pop 

ret 


call  ES:DI  =  request  header 
extracts  address,  start,  count 


save  request  header  address 
starting  sector  number 
sectors  requested 


es 
di 

ax, es: [di+1 4h] 

Xf rsec, ax 
ax, es : [di+1 2h] 

Xfrreq, ax 

di, es : [di+Oeh]  ;  requester's  buffer  address 
word  ptr  Xfraddr,di 
word  ptr  Xfraddr+2,es 

Xfrcnt,0  ;  initialize  sectors  transferred  count 

di  ;  restore  request  header  address 

es 


Setup  endp 

Figure  15-15.  Continued. 
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Init  proc  near 


;  command  code  0  =  Initialize  driver 
;  on  entry  ES:DI  =  request  header 


mov 

add 

mov 

add 

mov 

mov 


ax,  cs 

ax, Driver_len 
Secseg, ax 
ax, 1 OOOh 
es : [di+1 Oh] , ax 
word  ptr  es : [di+Oeh] , 0 


calculate  segment  base  for  sector 
storage  and  save  it 

add  1000H  paras  (64  KB)  and 
set  address  of  free  memory 


call  Format  ;  format  the  RAMdisk 

call  Signon  ;  display  driver  identification 

les  di,cs;RHPtr  ;  restore  ES:DI  =  request  header 

;  set  logical  units  =  1 
mov  byte  ptr  es : [di+Odh] , 1 

;  set  address  of  BPB  array 
mov  word  ptr  es : [di+1 2h] , of f set  Array 
mov  word  ptr  es : [di+1 4h] , cs 

xor  ax, ax  ;  return  success  status 

ret 

Init  endp 


Format 


proc 

near 

;  format  the  RAMdisk  area 

mov 

es, Secseg 

;  first  zero  out  RAMdisk 

xor 

di,di 

mov 

cx, SOOOh 

;  32  K  words  =  64  KB 

xor 

ax,  ax 

cld 

rep 

stosw 

mov 

ax,  0 

;  get 

address  of  logical 

call 

Mapsec 

;  sector  zero 

mov 

si, offset  Bootrec 

mov 

cx, Bootrec_len 

rep  1 

movsb 

;  and 

copy  boot  record  to 

it 

mov 

ax, word  ptr 

BPB+3 

call 

Mapsec 

;  get 

address  of  1 st  FAT 

sector 

mov 

al,byte  ptr 

BPB+Oah 

mov 

es : [di] , al 

;  put 

media  ID  byte  into 

it 

mov 

word  ptr  es 

:  [di+1],-1 

mov 

ax, word  ptr 

BPB+3 

add 

ax, word  ptr 

BPB+Obh 

call 

Mapsec 

;  get 

address  of  1 st  directory 

Figure  15-15.  Continued. 
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mov  si, offset  Volname 

mov  cx, Volname_len 

rep  movsb  ;  copy  volume  label  to  it 

ret  ;  done  with  formatting 

Format  endp 


Signon 

proc 

near 

,*  driver  identification  message 

les 

di,RHPtr 

;  let  ES:DI  =  request  header 

mov 

al,es: [di+22] 

;  get  drive  code  from  header. 

add 

al, 'A' 

;  convert  it  to  ASCII,  and 

mov 

drive, al 

;  store  into  sign-on  message 

mov 

ah,30h 

;  get  MS-DOS  version 

int 

21h 

cmp 

al,2 

ja 

Signoni  , 

?  jump  if  version  3.0  or  later 

mov 

Ident1,eom  , 

?  version  2.x,  don't  print  drive 

Signoni 

mov 

ah,09H 

?  print  sign-on  message 
;  Function  09H  =  print  string 

mov 

dx, offset  Ident  , 

;  DS:DX  =  address  of  message 

int 

21h 

?  transfer  to  MS-DOS 

ret 

;  back  to  caller 

Signon 

endp 

Ident 

db 

cr,lf,lf 

;  driver  sign-on  message 

db 

'TINYDISK  64 

KB  RAMdisk' 

db 

cr.  If 

Ident 1 

db 

'RAMdisk  will 

be  drive  ' 

Drive 

db 

’X:  ' 

db 

cr, If, eom 

Volname  db 

'DOSREF-DISK' 

;  volume  label  for 

RAMdisk 

db 

08h 

;  attribute  byte 

db 

10  dup  (0) 

;  reserved  area 

dw 

0 

;  time  =  00:00 

dw 

OfOlh 

;  date  =  August  1 , 

1987 

db 

6  dup  (0) 

;  reserved  area 

Volname_len  equ  $-volname 

Driver_len  dw  { ($-header ) / 1 6) +1  ;  driver  size  in  paragraphs 
-TEXT  ends 

end 

Figure  15-15.  Continued. 
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Subsequent  driver  Read  and  Write  calls  by  the  kernel  to  TINYDISK  function  as  though  they 
were  transferring  sectors  to  and  from  a  physical  storage  device  but  actually  only  copy  data 
from  one  area  in  mqpiory  to  another.  A  programmer  can  learn  a  great  deal  about  the  oper¬ 
ation  of  block-device  drivers  and  MS-DOS's  relationship  to  those  drivers  (such  as  the  order 
and  frequency  of  Media  Change,  Build  BPB,  Read,  Write,  and  Write  With  Verify  calls)  by 
inserting  software  probes  into  TINYDISK  at  appropriate  locations  and  monitoring  its 
behavior. 

TINYDISK. ASM  can  be  assembled,  linked,  and  converted  into  a  loadable  driver  with  the 
following  commands: 

OmASM  TINYDISK;  <Enter> 

C>LINK  TINYDISK;  <Enter> 

OEXE2BIN  TINYDISK.EXE  TINYDISK. SYS  <Enter> 

The  linker  will  display  the  warning  message  No  Stack  Segment',  this  message  can  be 
ignored.  The  driver  can  then  be  installed  by  adding  the  line 

DEVICE=TINYDISK. SYS 

to  the  CONFIG.SYS  file  and  restarting  the  system.  When  it  is  loaded,  TINYDISK  displays  a 
sign-on  message  and  the  drive  letter  that  it  was  assigned  if  it  is  running  under  MS-DOS  ver¬ 
sion  3.0  or  later.  (If  the  host  system  is  MS-DOS  version  2.x,  this  information  is  not  provided 
to  the  driver.)  Files  can  then  be  copied  to  the  RAMdisk  as  though  it  were  a  small  but 
extremely  fast  disk  drive. 


Ray  Duncan 
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Article  16 

Writing  Applications  for 
Upward  Compatibility 


One  of  the  major  concerns  of  the  designers  of  Microsoft  OS/2  was  that  it  be  backwardly 
compatible — that  is,  that  programs  written  to  run  under  MS-DOS  versions  2  and  3  be  able 
to  run  on  MS  OS/2.  A  major  concern  for  present  application  programmers  is  that  their  pro¬ 
grams  run  not  only  on  current  versions  of  MS-DOS  (and  MS  OS/2)  but  also  on  future  ver¬ 
sions  of  MS-DOS.  Ensuring  such  upward  compatibility  involves  both  hardware  issues  and 
operating-system  issues. 


Hardware  Issues 

A  basic  requirement  for  ensuring  upward  compatibility  is  hardware-independent  code.  If 
you  bypass  system  services  and  directly  program  the  hardware — such  as  the  system  inter¬ 
rupt  controller,  the  system  clock,  and  the  enhanced  graphics  adapter  (EGA)  registers — 
your  application  will  not  run  on  future  versions  of  MS-DOS. 

Protected  mode  compatibility 

The  80286  and  the  80386  microprocessors  can  operate  in  two  incompatible  modes:  real 
mode  and  protected  mode.  When  either  chip  is  operating  in  real  mode,  it  is  perceived  by 
the  operating  system  and  programs  as  a  fast  8088  chip.  Applications  written  for  the  8086 
and  8088  run  the  same  on  the  80286  and  the  80386 — only  faster.  They  cannot,  however, 
take  advantage  of  80286  and  80386  features  unless  they  can  run  in  protected  mode. 

Following  the  guidelines  below  will  minimize  the  work  necessary  to  convert  a  real  mode 
program  to  protected  mode  and  will  also  allow  a  program  to  use  a  special  subset  of  the 
MS  OS/2  Applications  Program  Interface  (API) — Family  API.  A  binary  program  (.EXE) 
that  uses  the  family  API  can  run  in  either  protected  mode  or  real  mode  under  MS  OS/2  and 
subsequent  systems,  but  it  can  run  only  in  real  mode  under  MS-DOS  version  3. 

Family  API 

The  Family  API  requires  that  the  application  use  a  subset  of  the  MS  OS/2  Dynamic  Link 
System  API.  Special  tools  link  the  application  with  a  special  library  that  implements  the 
subset  MS  OS/2  system  services  in  the  MS-DOS  version  3  environment.  Many  of  these  ser¬ 
vices  are  implemented  by  calling  the  appropriate  Interrupt  21H  subfunction;  some  are 
implemented  in  the  special  library  itself. 
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When  a  Family  API  application  is  loaded  under  MS  OS/2  protected  mode,  MS  OS/2  ignores 
the  special  library  code  and  loads  only  the  application  itself.  MS  OS/2  then  provides  the 
requested  services  in  the  normal  fashion.  However,  MS-DOS  version  3  loads  the  entire 
package — the  application  and  the  special  library — because  the  Family  API  .EXE  file  is 
constructed  to  look  like  an  MS-DOS  3  .EXE  file. 

linear  f;^  segmented  memory 

The  protected  mode  and  the  real  mode  of  the  80286  and  the  80386  are  compatible  except 
in  the  area  of  segmentation.  The  8086  has  been  described  as  a  segmented  machine,  but  it 
is  actually  a  linear  memory  machine  with  offset  registers.  When  a  memory  address  is  gen¬ 
erated,  the  value  in  one  of  the  “segment”  registers  is  multiplied  by  l6  and  added  as  a 
displacement  to  the  offset  value  supplied  by  the  instruction’s  addressing  mode.  No  length 
information  is  associated  with  each  “segment”;  the  “segment”  register  supplies  only  a 
20-bit  addressing  offset.  Programs  routinely  use  this  by  computing  a  20-bit  address  and 
then  decomposing  it  into  a  l6-bit  “segment”  value  and  a  l6-bit  displacement  value  so  that 
the  address  can  be  referenced. 

The  protected  mode  of  the  80286  and  the  80386,  however,  is  truly  segmented.  A  value 
placed  in  a  segment  register  selects  an  entry  from  a  descriptor  table;  that  entry  contains 
the  addressing  offset,  a  segment  length,  and  permission  bits.  On  the  8086,  the  so-called 
segment  component  of  an  address  is  multiplied  by  16  and  added  to  the  offset  component, 
producing  a  20-bit  physical  address.  Thus,  if  you  take  an  address  in  the  segment:offset 
form,  add  4  to  the  segment  value,  and  subtract  64  (that  is,  4  *16)  from  the  offset  value,  the 
new  address  references  exactly  the  same  location  as  the  old  address.  On  the  80286  and 
the  80386  in  protected  mode,  however,  segment  values,  called  segment  selectors,  have  no 
direct  correspondence  to  physical  addresses.  In  other  words,  in  8086  mode,  the  two 
address  forms 

1000,^:0345,^ 

and 

1004,^:0305,^ 

reference  the  same  memory  location,  but  in  protected  mode  these  two  forms  reference 
totally  different  locations. 

Creating  segment  values 

This  architectural  difference  gives  rise  to  the  most  common  cause  of  incompatibility — the 
program  performs  addressing  arithmetic  to  compute  “segment”  values.  Any  program  that 
uses  the  20-bit  addressing  scheme  to  create  or  to  compute  a  value  to  be  loaded  in  a  seg¬ 
ment  register  cannot  be  converted  to  run  in  protected  mode.  To  be  protected  mode  com¬ 
patible,  a  program  must  treat  the  8086’s  so-called  segments  as  true  segments. 

To  create  a  program  that  does  this,  write  according  to  the  following  guidelines: 

1.  Do  not  generate  any  segment  values.  Use  only  the  segment  values  supplied  by 

MS-DOS  calls  and  those  placed  in  the  segment  registers  when  MS-DOS  loaded  your 
program.  The  exception  is  “huge  objects” — memory  objects  larger  than  64  KB.  In 
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this  case,  MS  OS/2  provides  a  base  segment  number  and  a  “segment  offset  value.” 

The  returned  segment  number  selects  the  first  64  KB  of  the  object  and  the  segment 
number,  plus  the  segment  offset  value  address  the  second  64  KB  of  the  object.  Like¬ 
wise,  the  returned  segment  value  plus  (segment  offset  value)  selects  the  N+1 

64  KB  piece  of  the  huge  object.  Write  real  mode  code  in  this  same  fashion,  using 
4096  as  the  segment  offset  value.  When  you  convert  your  program,  you  can  substitute 
the  value  provided  by  MS  OS/2. 

2.  Do  not  address  beyond  the  allocated  length  of  a  segment. 

3.  Do  not  use  segment  registers  as  scratch  registers  by  placing  general  data  in  them. 
Place  only  valid  segment  values,  supplied  by  MS-DOS,  in  a  segment  register.  The  one 
exception  is  that  you  can  place  a  zero  value  in  a  segment  register,  perhaps  to  indicate 
“no  address.”  You  can  place  the  zero  in  the  segment  register,  but  you  cannot  reference 
memory  using  that  register;  you  can  only  load/store  or  push/pop  it. 

4.  Do  not  use  CS:  overrides  on  instructions  that  store  into  memory.  It  is  impossible  to 
store  into  a  code  segment  in  protected  mode. 

CPU  speed 

Because  various  microprocessors  and  machine  configurations  execute  at  different  speeds, 
a  program  should  not  contain  timing  loops  that  depend  on  CPU  speed.  Specifically,  a  pro¬ 
gram  should  not  establish  CPU  speed  during  initialization  and  then  use  that  value  for  tim¬ 
ing  loops  because  the  preemptive  scheduling  of  MS  OS/2  and  future  operating  systems 
can  “take  away”  the  CPU  at  any  time  for  arbitrary  and  unpredictable  lengths  of  time.  (In 
any  case,  time  should  not  be  wasted  in  a  timing  loop  when  other  processes  could  be  using 
system  resources.) 

Program  timing 

Programs  must  measure  the  passage  of  time  carefully.  They  can  use  the  system  clock-tick 
interrupt  while  directly  interfacing  with  the  user,  but  no  clock  ticks  will  be  seen  by  real 
mode  programs  when  the  user  switches  the  screen  interface  to  another  program. 

It  is  recommended  that  applications  use  the  time-of-day  system  interface  to  determine 
elapsed  time.  To  facilitate  conversion  to  MS  OS/2  protected  mode,  programs  should  encap¬ 
sulate  time-of-day  or  elapsed-time  functions  into  subroutines. 

BIOS 


Avoid  BIOS  interrupt  interfaces  except  for  Interrupt  lOH  (the  screen  display  functions) 
and  Interrupt  16H  (the  keyboard  functions).  Interrupt  lOH  functions  are  contained  in  the 
MS  OS/2  VIO  package,  and  Interrupt  16H  functions  are  in  the  MS  OS/2  KBD  package. 
Other  BIOS  interrupts  provide  functions  that  are  available  under  MS  OS/2  only  in  con¬ 
siderably  modified  forms. 

Special  operations 

Uncommon,  or  special,  operations  and  instructions  can  produce  varied  results,  depending 
on  the  microprocessor.  For  example,  when  a  “divide  by  0”  trap  is  taken  on  an  8086,  the 
stack  frame  points  to  the  instruction  after  the  fault;  when  such  action  is  taken  on  the  80286 
and  80386,  the  return  address  points  to  the  instruction  that  caused  the  fault.  The  effect  of 
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pushing  the  SP  register  is  different  between  the  80286  and  the  80386  as  well.  See  Appen¬ 
dix  M:  8086/8088  Software  Compatibility  Issues.  Write  your  program  to  avoid  these 
problem  areas. 


Operating-System  Issues 

Basic  to  writing  programs  that  will  run  on  future  operating  systems  is  writing  code  that  is 
not  version  specific.  Incorporating  special  version-specific  features  in  a  program  will  vir¬ 
tually  ensure  that  the  program  will  be  incompatible  with  future  versions  of  MS-DOS  and 
MS  OS/2. 

Following  the  guidelines  below  will  not  necessarily  ensure  your  program’s  compatibility, 
but  it  will  facilitate  converting  the  program  or  using  the  Family  API  to  produce  a  dual¬ 
mode  binary  program. 

Filenames 

MS-DOS  versions  2  and  3  silently  truncate  a  filename  that  is  longer  than  eight  characters 
or  an  extension  that  is  longer  than  three  characters.  MS-DOS  generates  no  error  message 
when  performing  this  task.  In  real  mode,  MS  OS/2  also  silently  truncates  a  filename  or  ex¬ 
tension  that  exceeds  the  maximum  length;  in  protected  mode,  however,  it  does  not. 
Therefore,  a  real  mode  application  program  needs  to  perform  this  truncating  function. 

The  program  should  check  the  length  of  the  filenames  that  it  generates  or  that  it  obtains 
from  a  user  and  refuse  names  that  are  longer  than  the  eight-character  maximum.  This  pre¬ 
vents  improperly  formatted  names  from  becoming  embedded  in  data  and  control  files — a 
situation  that  could  cause  a  protected  mode  version  of  the  application  to  fail  when  it  pre¬ 
sents  that  invalid  name  to  the  operating  system. 

When  you  convert  your  program  to  protected  mode  API,  remove  the  length-checking 
code;  MS  OS/2  will  check  the  length  and  return  an  error  code  as  appropriate.  Future  file 
systems  will  support  longer  filenames,  so  it’s  important  that  protected  mode  programs  sim¬ 
ply  present  filenames  to  the  operating  system,  which  is  then  responsible  for  judging  their 
validity. 

Other  MS-DOS  version  2  and  3  elements  have  fixed  lengths,  including  the  current  directory 
path.  To  be  upwardly  compatible,  your  program  should  accept  whatever  length  is  provided 
by  the  user  or  returned  from  a  system  call  and  rely  on  MS  OS/2  to  return  an  error  message 
if  a  length  is  inappropriate.  The  exception  is  filename  length  in  real  mode  non-Family  API 
programs:  These  programs  should  enforce  the  eight-character  maximum  because  MS-DOS 
versions  2  and  3  fail  to  do  so. 

File  truncation 

Files  are  truncated  by  means  of  a  zero-length  write  under  MS-DOS  versions  2  and  3;  under 
MS  OS/2  in  protected  mode,  files  are  truncated  with  a  special  API.  File  truncation  opera¬ 
tions  should  be  encapsulated  in  a  special  routine  to  facilitate  conversion  to  MS  OS/2  pro¬ 
tected  mode  or  the  Family  API. 
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File  searches 

MS-DOS  versions  2  and  3  never  close  file-system  searches  (Find  First  File/Find  Next  File). 
The  returned  search  contains  the  information  necessary  for  MS-DOS  to  continue  the 
search  later,  and  if  the  search  is  never  continued,  no  harm  is  done. 

MS  OS/2,  however,  retains  the  necessary  search  continuation  information  in  an  internal 
structure  of  limited  size.  For  this  reason,  your  program  should  not  depend  on  more  than 
about  10  simultaneous  searches  and  it  should  be  able  to  close  searches  when  it  is  done.  If 
your  program  needs  to  perform  more  than  about  10  searches  simultaneously,  it  should  be 
able  to  close  a  search,  restart  it  later,  and  advance  to  the  place  where  the  program  left  off, 
rather  than  depending  on  MS  OS/2  to  continue  the  search. 

MS  OS/2  further  provides  a  Find  Close  function  that  releases  the  internal  search  infor¬ 
mation.  Protected  mode  programs  should  use  this  call  at  the  end  of  every  search  se¬ 
quence.  Because  MS-DOS  versions  2  and  3  have  no  such  call,  your  program  should  call  a 
dummy  procedure  by  this  name  at  the  appropriate  locations.  Then  you  can  convert  your 
program  to  the  protected  mode  API  or  to  the  Family  API  without  reexamining  your 
algorithms. 

Note:  Receiving  a  “No  more  files”  return  code  from  a  search  does  not  implicitly  close  the 
search;  all  search  closes  must  be  explicit. 

The  Family  API  allows  only  a  single  search  at  a  time.  To  circumvent  this  restriction,  code 
two  different  Find  Next  File  routines  in  your  program — one  for  MS  OS/2  protected  mode 
and  one  for  MS-DOS  real  mode — and  use  the  Family  API  function  that  determines  the 
program’s  current  environment  to  select  the  routine  to  execute. 

MS-DOS  calls 

A  program  that  uses  only  the  Interrupt  21H  functions  listed  below  is  guaranteed  to  work 
in  the  Compatibility  Box  of  MS  OS/2  and  will  be  relatively  easy  to  modify  for  MS  OS/2 
protected  mode. 


Function  Name 


ODH 

Disk  Reset 

OEH 

Select  Disk 

19H 

Get  Current  Disk 

lAH 

Set  DTA  Address 

25H 

Set  Interrupt  Vector 

2AH 

Get  Date 

2BH 

Set  Date 

2CH 

Get  Time 

2EH 

Set/Reset  Verify  Flag 

2FH 

Get  DTA  Address 

(more) 
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Function 

Name 

30H 

Get  MS-DOS  Version  Number 

33H 

Get/Set  Control-C  Check  Flag 

35H 

Get  Interrupt  Vector 

36H 

Get  Disk  Free  Space 

38H 

Get/Set  Current  Country 

39H 

Create  Directory 

3AH 

Remove  Directory 

3BH 

Change  Current  Directory 

3CH 

Create  File  with  Handle 

3DH 

Open  File  with  Handle 

3EH 

Close  File 

3FH 

Read  File  or  Device 

40H 

Write  File  or  Device 

41H 

Delete  File 

42H 

Move  File  Pointer 

43H 

Get/Set  File  Attributes 

44H 

lOCTL  (all  subfunctions) 

45H 

Duplicate  File  Handle 

46H 

Force  Duplicate  File  Handle 

47H 

Get  Current  Directory 

48H 

Allocate  Memory  Block 

49H 

Free  Memory  Block 

4AH 

Resize  Memory  Block 

4BH 

Load  and  Execute  Program  (EXEC) 

4CH 

Terminate  Process  with  Return  Code 

4DH 

Get  Return  Code  of  Child  Process 

4EH 

Find  First  File 

4FH 

Find  Next  File 

54H 

Get  Verify  Flag 

56H 

Rename  File 

57H 

Get/Set  Date/Time  of  File 

59H 

Get  Extended  Error  Information 

5AH 

Create  Temporary  File 

5BH 

Create  New  File 

5CH 

Lock/Unlock  File  Region 

FCBs 


FCBs  are  not  supported  in  MS  OS/2  protected  mode.  Use  handle-based  calls  instead. 
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Interrupt  calls 

MS-DOS  versions  2  and  3  use  an  interrupt-based  interface;  MS  OS/2  protected  mode  uses 
a  procedure-call  interface.  Write  your  code  to  accommodate  this  difference  by  encap¬ 
sulating  the  interrupt-based  interfaces  into  individual  subroutines  that  can  then  easily  be 
modified  to  use  the  MS  OS/2  procedure-call  interface. 

System  call  register  usage 

The  MS  OS/2  procedure-call  interface  preserves  all  registers  except  AX  and  FLAGS.  Write 
your  program  to  assume  that  the  contents  of  AX  and  the  contents  of  any  register  modified 
by  MS-DOS  version  2  and  3  interrupt  interfaces  are  destroyed  at  each  system  call,  regard¬ 
less  of  the  success  or  failure  of  that  call. 

Flush/Commit  calls 

Your  program  should  issue  Flush/Commit  calls  where  necessary — for  example,  after 
writing  out  the  user’s  work  file — but  no  more  than  necessary.  Because  MS  OS/2  is  multi¬ 
tasking,  the  floppy  disk  that  contains  the  files  to  be  flushed  may  not  be  in  the  drive.  In 
such  a  case,  MS  OS/2  prompts  the  user  to  insert  the  proper  floppy  disk.  As  a  result,  too 
frequent  flushes  could  generate  a  great  many  Insert  disk  messages  and  degrade  the 
system’s  usability. 

Seeks 


Seeks  to  negative  offsets  and  to  devices  also  create  compatibility  issues. 

To  negative  offsets 

Your  program  should  not  attempt  to  seek  to  a  negative  file  location.  A  negative  seek  offset 
is  permissible  as  long  as  the  sum  of  the  seek  offset  and  the  current  file  position  is  positive. 
MS-DOS  versions  2  and  3  allow  seeking  to  a  negative  offset  as  long  as  you  do  not  attempt  to 
read  or  write  the  file  at  that  offset.  MS  OS/2  and  subsequent  systems  return  an  error  code 
for  negative  net  offsets. 

On  devices 

Your  program  should  not  issue  seeks  to  devices  (such  as  AUX,  COM,  and  so  on).  Doing  so 
produces  an  error  under  MS  OS/2. 

Error  codes 

Because  future  releases  of  the  operating  system  may  return  new  error  codes  to  system 
calls,  you  should  write  code  that  is  open-ended  about  error  codes — that  is,  write  your  pro¬ 
gram  to  deal  with  error  codes  beyond  those  currently  defined.  You  can  generally  do  this 
by  including  special  handling  for  any  codes  that  require  special  treatment,  such  as  “File  not 
found,”  and  by  taking  a  generic  course  of  action  for  all  other  errors.  The  MS  OS/2  pro¬ 
tected  mode  API  and  the  Family  API  have  an  interface  that  contains  a  message  describing 
the  error;  this  message  can  be  displayed  to  the  user.  The  interface  also  returns  error 
classification  information  and  a  recommended  action. 
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Multitasking  concerns 

Multitasking  is  a  feature  of  MS  OS/2  and  will  be  a  feature  of  all  future  versions  of  MS-DOS. 
The  following  guidelines  apply  to  all  programs,  even  to  those  written  for  MS-DOS  version 
3,  because  they  may  run  in  compatibility  mode  under  MS  OS/2. 

Disabling  interrupts 

Do  not  disable  interrupts,  typically  with  the  CLI  instruction.  The  consequences  of  doing  so 
depend  on  the  environment. 

In  real  mode  programs  under  MS  OS/2,  disabling  interrupts  works  normally  but  has  a 
negative  impact  on  the  system’s  ability  to  maintain  proper  system  throughput.  Communi¬ 
cations  programs  or  networking  applications  might  lose  data.  In  a  future  version  of  real 
mode  MS  OS/2-80386,  the  operating  system  will  disregard  attempts  to  disable  interrupts. 

Protected  mode  programs  under  MS  OS/2  can  disable  interrupts  only  in  special  Ring  2 
segments.  Disabling  interrupts  for  longer  than  100  microseconds  might  cause  communica¬ 
tions  programs  or  networking  applications  to  lose  data  or  break  connection.  A  future 
80386-specific  version  of  MS  OS/2  will  ignore  attempts  to  disable  interrupts  in  protected 
mode  programs. 

Measuring  system  resources 

Do  not  attempt  to  measure  system  resources  by  exhausting  them,  and  do  not  assume  that 
because  a  resource  is  available  at  one  time  it  will  be  available  later.  Remember:  System 
resources  are  being  shared  with  other  programs. 

For  example,  it  is  common  for  an  MS-DOS  version  3  application  to  request  1  MB  of  mem¬ 
ory.  The  system  cannot  fulfill  this  request,  so  it  returns  the  largest  amount  of  memory 
available.  The  application  then  requests  that  amount  of  memory.  Typically,  applications  do 
not  even  check  for  an  error  code  from  the  second  request.  They  routinely  request  all  avail¬ 
able  memory  because  their  creators  knew  that  no  other  application  could  be  in  the  system 
at  the  same  time.  This  practice  will  work  in  real  mode  MS  OS/2,  although  it  is  inefficient 
because  MS  OS/2  must  allocate  memory  to  a  program  that  has  no  effective  use  for  it.  How¬ 
ever,  this  practice  will  not  work  under  MS  OS/2  protected  mode  or  under  the  Family  API. 

Another  typical  resource-exhaustion  technique  is  opening  files  until  an  open  is  refused 
and  then  closing  unneeded  file  handles.  All  applications,  even  those  that  run  only  in  an 
MS  OS/2  real  mode  environment,  must  use  only  the  resources  they  need  and  not  waste 
system  resources;  in  a  multitasking  environment,  other  programs  in  the  system  usually 
need  those  resources. 

Sharing  rules 

Because  multiple  programs  can  run  under  MS  OS/2  simultaneously  and  because  the 
system  can  be  networked,  conflicts  can  occur  when  two  programs  try  to  access  the  same 
file.  MS  OS/2  handles  this  situation  with  special  file-sharing  support.  Although  programs 
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ignorant  of  file-sharing  rules  can  run  in  real  mode,  you  should  explicitly  specify  file¬ 
sharing  rules  in  your  program.  This  will  reduce  the  number  of  file-access  conflicts  the  user 
will  encounter. 

Miscellaneous  guidelines 

Do  not  use  undocumented  features  of  MS-DOS  or  undocumented  fields  such  as  those  in 
the  Find  First  File  buffer.  Also,  do  not  modify  or  store  your  own  values  in  such  areas. 

Maintain  at  least  2048  free  bytes  on  the  stack  at  all  times.  Future  releases  of  MS-DOS  may 
require  extra  stack  space  at  system  call  and  at  interrupt  time. 

Print  using  conventional  handle  writes  to  the  LPT  device(s).  For  example: 

fd  =  openC'LPTI”)  ; 
write (fd,  data,  datalen) ; 

Do  not  use  Interrupt  17H  (the  IBM  ROM  BIOS  printer  services),  writes  to  the  stdprn  han¬ 
dle  (handle  3),  or  special-purpose  Interrupt  21H  functions  such  as  05H  (Printer  Output). 
These  methods  are  not  supported  under  MS  OS/2  protected  mode  or  in  the  Family  API. 

Do  not  use  the  MS-DOS  standard  handles  stdaux  and  stdprn  (handles  3  and  4);  these 
handles  are  not  supported  in  MS  OS/2  protected  mode.  Use  only  stdin  (handle  0),  stdout 
(handle  1),  and  stderr  (handle  2).  Do  use  these  latter  handles  where  appropriate  and  avoid 
opening  the  CON  device  directly.  Avoid  Interrupt  21H  Functions  03H  (Auxiliary  Input)  and 
04H  (Auxiliary  Output),  which  are  polling  operations  on  stdaux. 


Summary 

A  tenet  of  MS  OS/2  design  was  flexibility:  Each  component  was  constructed  in  anticipa¬ 
tion  of  massive  changes  in  a  future  release  and  with  an  eye  toward  existing  versions  of 
MS-DOS.  Writing  applications  that  are  upwardly  and  backwardly  compatible  in  such  an 
environment  is  essential — and  challenging.  Following  the  guidelines  in  this  article  will 
ensure  that  your  programs  function  appropriately  in  the  MS-DOS/OS/2  operating- 
system  family. 


Gordon  Letwin 
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Article  17 
Windows 


Microsoft  Windows  is  an  operating  environment  that  runs  under  MS-DOS  versions  2.0 
and  later.  The  current  version  of  Windows,  version  2.0,  requires  either  a  fixed  disk  or  two 
double-sided  floppy-disk  drives,  at  least  320  KB  of  memory,  and  a  video  display  board 
and  monitor  capable  of  graphics  and  a  screen  resolution  of  at  least  640  (horizontal)  by  200 
(vertical)  pixels.  A  fixed  disk  and  640  KB  of  memory  provide  the  best  environment  for  run¬ 
ning  Windows;  a  mouse  or  other  pointing  device  is  optional  but  recommended. 

For  the  user,  Windows  provides  a  multitasking,  graphics-based  windowing  environment 
for  running  programs.  In  this  environment,  users  can  easily  switch  among  several  pro¬ 
grams  and  transfer  data  between  them.  Because  programs  specially  designed  to  run  under 
Windows  usually  have  a  consistent  user  interface,  the  time  spent  learning  a  new  program 
is  greatly  diminished.  Furthermore,  the  user  can  carry  out  command  functions  using  only 
the  keyboard,  only  the  mouse,  or  some  combination  of  the  two.  In  some  cases,  Windows 
(and  Windows  applications)  provides  several  different  ways  to  execute  the  same 
command. 

For  the  program  developer,  Windows  provides  a  wealth  of  high-level  routines  that  make 
it  easy  to  incorporate  menus,  scroll  bars,  and  dialog  boxes  (which  contain  controls,  such  as 
push  buttons  and  list  boxes)  into  programs.  Windows’  graphics  interface  is  device  inde¬ 
pendent,  so  programs  developed  for  Windows  work  with  every  video  display  adapter  and 
printer  that  has  a  Windows  driver  (usually  supplied  by  the  hardware  manufacturer).  Win¬ 
dows  also  includes  features  that  facilitate  the  translation  of  programs  into  foreign  lan¬ 
guages  for  international  markets. 

When  Windows  is  running,  it  shares  responsibility  for  managing  system  resources  with 
MS-DOS.  Thus,  programs  that  run  under  Windows  continue  to  use  MS-DOS  function  calls 
for  all  file  input  and  output  and  for  executing  other  programs,  but  they  do  not  use  MS-DOS 
for  display  or  printer  output,  keyboard  or  mouse  input,  or  memory  management.  Instead, 
they  use  functions  provided  by  Windows. 


Program  Categories 

Programs  that  run  under  Windows  can  be  divided  into  three  categories: 

1 .  Programs  specially  designed  for  the  Windows  environment.  Examples  of  such  pro¬ 
grams  include  Clock  and  Calculator,  which  come  with  Windows.  Microsoft  Excel  is 
also  specially  designed  for  Windows.  Other  programs  of  this  type  (such  as  Aldus’s 
Pagemaker)  are  available  from  software  vendors  other  than  Microsoft.  Programs  in 
this  category  cannot  run  under  MS-DOS  without  Windows. 

2.  Programs  designed  to  run  under  MS-DOS  but  that  can  usually  be  run  in  a  window 
along  with  programs  designed  specially  for  Windows.  These  programs  do  not  require 


Section  II:  Programming  in  the  MS-DOS  Environment  499 


Part  D:  Directions  of  MS-DOS 


large  amounts  of  memory,  do  not  write  directly  to  the  display,  do  not  use  graphics, 
and  do  not  alter  the  operation  of  the  keyboard  interrupt.  They  cannot  use  the  mouse, 
the  Windows  application-program  interface  (such  as  menus  and  dialog  boxes),  or 
the  graphics  services  that  Windows  provides.  MS-DOS  utilities,  such  as  EDLIN  and 
CHKDSK,  are  examples  of  programs  in  this  category. 

3.  Programs  designed  to  run  under  MS-DOS  but  that  require  large  amounts  of  memory, 
write  directly  to  the  display,  use  graphics,  or  alter  the  operation  of  the  keyboard  inter¬ 
rupt.  When  Windows  runs  such  a  program,  it  must  suspend  operation  of  all  other 
programs  running  in  Windows  and  allow  the  program  to  use  the  full  screen.  In  some 
cases,  Windows  cannot  switch  back  to  its  normal  display  until  the  program  termi¬ 
nates.  Microsoft  Word  and  Lotus  1-2-3  are  examples  of  programs  in  this  category. 

The  programs  in  categories  2  and  3  are  sometimes  called  standard  applications.  To  run 
one  of  these  programs  in  Windows,  the  user  must  create  a  PIF  file  (Program  Information 
File)  that  describes  how  much  memory  the  program  requires  and  how  it  uses  the  com¬ 
puter’s  hardware. 

Although  the  ability  to  run  existing  MS-DOS  programs  under  Windows  benefits  the  user, 
the  primary  purpose  of  Windows  is  to  provide  an  environment  for  specially  designed  pro¬ 
grams  that  take  full  advantage  of  the  Windows  interface.  This  discussion  therefore  concen¬ 
trates  almost  exclusively  on  programs  written  for  the  Windows  2.0  environment. 


The  Windows  Display 

Figure  17-1  shows  a  typical  Windows  display  running  several  programs  that  are  included 
with  the  retail  version  of  Windows  2.0. 

The  display  is  organized  as  a  desktop,  with  each  program  occupying  one  or  more  rect¬ 
angular  windows  that,  unlike  the  tiled  (juxtaposed)  windows  typical  of  earlier  versions, 
can  be  overlapped.  Only  one  program  is  active  at  any  time — usually  the  program  that  is 
currently  receiving  keyboard  input.  Windows  displays  the  currently  active  program  on  top 
of  (overlying)  the  others.  Programs  such  as  CLOCK  and  TERMINAL  that  are  not  active 
continue  to  run  normally,  but  do  not  receive  keyboard  input. 

The  user  can  make  another  program  active  by  pressing  and  releasing  (clicking)  the  mouse 
button  when  the  mouse  cursor  is  positioned  in  the  new  program’s  window  or  by  pressing 
either  the  Alt-Tab  or  Alt-Esc  key  combination.  Windows  then  brings  the  new  active  pro¬ 
gram  to  the  top. 

Most  Windows  programs  allow  their  windows  to  be  moved  to  another  part  of  the  display 
or  to  be  resized  to  occupy  smaller  or  larger  areas.  Most  of  these  programs  can  also  be  max¬ 
imized  to  fill  the  entire  screen  or  minimized — generally  as  a  small  icon  displayed  at  the 
bottom  of  the  screen — to  occupy  a  small  amount  of  display  space. 
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Figure  17-1.  A  typical  Windows  display. 

Parts  of  the  window 

Figure  17-2  shows  the  Windows  NOTEPAD  program,  with  the  different  parts  of  the  win¬ 
dow  identified.  NOTEPAD  is  a  small  ASCII  text  editor  limited  to  files  of  l6  KB.  The  various 
parts  of  the  NOTEPAD  window  (similar  to  all  Windows  programs)  are  described  in  this 
section. 

Title  bar  (or  caption  bar).  The  title  bar  identifies  the  program  and,  if  applicable,  the  data 
file  currently  loaded  into  the  program.  For  example,  the  NOTEPAD  window  shown  in 
Figure  17-2  on  the  next  page  has  the  file  WIN.INI  loaded  into  memory.  Windows  uses  dif¬ 
ferent  title-bar  colors  to  distinguish  the  active  window  from  inactive  windows.  The  user 
can  move  a  window  to  another  part  of  the  display  by  pressing  the  mouse  button  when  the 
mouse  pointer  is  positioned  anywhere  on  the  title  bar  and  dragging  (moving)  the  mouse 
while  the  button  is  pressed. 

System-menu  icon.  When  the  user  clicks  a  system-menu  icon  with  the  mouse  (or  presses 
Alt-Spacebar),  Windows  displays  a  system  menu  like  that  shown  in  Figure  17-3.  (Most  Win¬ 
dows  programs  have  identical  system  menus.)  The  user  selects  a  menu  item  in  one  of 
several  ways:  clicking  on  the  item;  moving  the  highlight  bar  to  the  item  with  the  cursor- 
movement  keys  and  then  pressing  Enter;  or  pressing  the  letter  that  is  underlined  in  the 
menu  item  (for  example,  n  for  Minimize. 

The  keyboard  combinations  (Alt  plus  function  key)  at  the  right  of  the  system  menu  are 
keyboard  accelerators.  Using  a  keyboard  accelerator,  the  user  can  select  system-menu 
options  without  first  displaying  the  system  menu. 


Section  II:  Programming  in  the  MS-DOS  Environment  50 1 


Part  D:  Directions  of  MS-DOS 


System -menu 


Title  bar 


Minimize 


Eile^  Edit  Search 


Tintl] 

iCountry=1 

iDate=0 

iCurrency=0 

iDigits=2 

iTine=0 

iLzero=0 

s1159=fiM 

s2359=PM 

sCurrency=$ 

sThousand=, 

sDecinal=. 

sDate=- 

sTiine=: 

sList=, 

dialog=yes 


[ports] 

;  To  output  to  a  file  make  an  entry  in  this  section  of  the  form 

;  filename. PRN  followed  by  an  equal  sign. 

;  The  filename  will  appear  in  the  Control  Panel  Connections  dialog  and 

;  any  printer  may  then  be  connected  to  this  file  and  all  printing  will 
;  be  done  to  this  file. 
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Figure  1 7-2.  The  Windows  NOTEPAD  program,  with  different  parts  of  the  display  labeled. 


The  six  options  on  the  standard  system  menu  are 

•  Restore:  Return  the  window  to  its  previous  position  and  size  after  it  has  been 
minimized  or  maximized. 

•  Move:  Allow  the  window  to  be  moved  with  the  cursor-movement  keys. 

•  Size:  Allow  the  window  to  be  resized  with  the  cursor-movement  keys. 

•  Minimize:  Display  the  window  in  its  iconic  form. 

•  Maximize:  Allow  the  window  to  occupy  the  full  screen. 

•  Close:  End  the  program. 

Windows  displays  an  option  on  the  system  menu  in  grayed  text  to  indicate  that  the  option 
is  not  currently  valid.  In  the  system  menu  shown  in  Figure  17-3,  for  example,  the  Restore 
option  is  grayed  because  the  window  is  not  in  a  minimized  or  maximized  form. 
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Figure  1 7-3-  A  system  menu,  displayed  either  when  the  user  clicks  the  system-menu  icon  (top  left  corner)  or 
presses  Alt-Spacebar. 


502  The  MS-DOS  Encyclopedia 


Article  17:  Windows 


i  O  l<X^| - Restore  icon 

Figure  17-4.  The  restore  icon,  which  replaces  the  maximize  icon  when  a  window  is  expanded  to  fill 
the  entire  screen. 

Minimize  icon.  When  the  user  clicks  on  the  minimize  icon  with  the  mouse,  Windows 
displays  the  program  in  its  iconic  form. 

Maximize  icon.  Clicking  on  the  maximize  icon  expands  the  window  to  fill  the  full  screen. 
Windows  then  replaces  the  maximize  icon  with  a  restore  icon  (shown  in  Figure  17-4). 
Clicking  on  the  restore  icon  restores  the  window  to  its  previous  size  and  position. 

Programs  that  use  a  window  of  a  fixed  size  (such  as  the  CALC.EXE  calculator  program 
included  with  Windows)  do  not  have  a  maximize  icon. 

Menu  bar.  The  menu  bar,  sometimes  called  the  program's  main  or  top-level  menu,  dis¬ 
plays  keywords  for  several  sets  of  commands  that  differ  from  program  to  program. 

When  the  user  clicks  on  a  main-menu  item  with  the  mouse  or  presses  the  Alt  key  and  the 
underlined  letter  in  the  menu  text,  Windows  displays  a  pop-up  menu  for  that  item.  The 
pop-up  menu  for  NOTEPAD’S  keyword  File  is  shown  in  Figure  17-5.  Items  are  selected 
from  a  pop-up  menu  in  the  same  way  they  are  selected  from  the  system  menu. 

A  Windows  program  can  display  options  on  the  menu  in  grayed  text  to  indicate  that  they 
are  not  currently  valid.  The  program  can  also  display  checkmarks  to  the  left  of  pop-up 
menu  itenis  to  indicate  which  of  several  options  have  been  selected  by  the  user. 

In  addition,  items  on  a  pop-up  menu  can  be  followed  by  an  ellipsis  (...)  to  indicate  that 
selecting  the  item  invokes  a  dialog  box  that  prompts  the  user  for  additional  information — 
more  than  can  be  provided  by  the  menu. 

Client  area.  The  client  area  of  the  window  is  where  the  program  displays  data.  In  the  case 
of  the  NOTEPAD  program  shown  in  Figure  17-2,  the  client  area  displays  the  file  currently 
being  edited.  A  program’s  handling  of  keyboard  and  mouse  input  within  the  client  area 
depends  on  the  type  of  work  it  does. 

Scroll  bars.  Programs  that  cannot  display  all  the  data  in  a  file  within  the  client  area  of  the 
window  often  have  a  horizontal  scroll  bar  across  the  bottom  and  a  vertical  scroll  bar  down 
the  right  edge.  Both  types  of  scroll  bars  have  a  small,  boxed  arrow  at  each  end  to  indicate 
the  direction  in  which  to  scroll.  In  the  NOTEPAD  window  in  Figure  17-2,  for  example, 
clicking  on  the  up  arrow  of  the  vertical  scroll  bar  moves  the  data  within  the  window  down 


Figure  1 7-5.  The  NOTEPAD  program 's  pop-up file  menu. 
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one  line.  Clicking  on  the  shaded  part  of  the  vertical  scroll  bar  above  the  thumb  (the  box 
near  the  middle)  moves  the  data  within  the  client  area  of  the  window  down  one  screen; 
clicking  below  the  thumb  moves  the  data  up  one  screen.  The  user  can  also  drag  the  thumb 
with  the  mouse  to  move  to  a  relative  position  within  the  file. 

Windows  programs  often  include  a  keyboard  interface  (generally  relying  on  the  cursor- 
movement  keys)  to  duplicate  the  mouse-based  scroll-bar  commands. 

Window  border.  The  window  border  is  a  thick  frame  surrounding  the  entire  window.  It  is 
segmented  into  eight  sections  that  represent  the  four  sides  and  four  corners  of  the  window. 
The  user  can  change  the  size  of  a  window  by  dragging  the  window  border  with  the 
mouse.  Dragging  a  corner  section  moves  two  adjacent  sides  of  the  border. 

When  a  program  is  maximized  to  fill  the  full  screen,  Windows  does  not  draw  the  window 
border.  Programs  that  use  a  window  of  a  fixed  size  do  not  have  a  window  border  either. 

Dialog  boxes 

When  a  pop-up  menu  is  not  adequate  for  all  the  command  options  a  program  requires,  the 
program  can  display  a  dialog  box.  A  dialog  box  is  a  pop-up  window  that  contains  various 
controls  in  the  form  of  push  buttons,  check  boxes,  radio  buttons,  list  boxes,  and  text  and 
edit  fields.  Programmers  can  also  design  their  own  controls  for  use  in  dialog  boxes.  A  user 
fills  in  a  dialog  box  and  then  clicks  on  a  button,  such  as  OK,  or  presses  Enter  to  indicate 
that  the  information  can  be  processed  by  the  program. 

Most  Windows  programs  use  a  dialog  box  to  open  an  existing  data  file  and  load  it  into  the 
program.  The  program  displays  the  dialog  box  when  the  user  selects  the  Open  option  on 
the  File  pop-up  menu.  The  sample  dialog  box  shown  in  Figure  17-6  is  from  the  NOTEPAD 
program. 

The  list  box  displays  a  list  of  all  valid  disk  drives,  the  subdirectories  of  the  current  direc¬ 
tory,  and  all  the  filenames  in  the  current  directory,  including  the  filename  extension  used 
by  the  program.  (NOTEPAD  uses  the  extension  .TXT  for  its  data  files.)  The  user  can  scroll 
through  this  list  box  and  change  the  current  drive  or  subdirectory  or  select  a  filename  with 
the  keyboard  or  the  mouse.  The  user  can  also  perform  these  actions  by  typing  the  name 
directly  into  the  edit  field. 
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buttons 
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Figure  1 7-6.  A  dialog  box  from  the  NOTEPAD  program,  with  parts  labeled. 
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Figure  17-7.  A  dialog  box from  the  TERMINAL  program,  with  parts  labeled. 

Clicking  the  Open  button  (or  pressing  Enter)  indicates  to  NOTEPAD  that  a  file  has  been 
selected  or  that  a  new  drive  or  subdirectory  has  been  chosen  (in  this  case,  the  program 
displays  the  files  on  the  new  drive  or  subdirectory).  Clicking  the  Cancel  button  (or  press¬ 
ing  Esc)  tells  NOTEPAD  to  close  the  dialog  box  without  loading  a  new  file. 

Figure  17-7  shows  a  different  dialog  box — this  one  from  the  Windows  TERMINAL  com¬ 
munications  program.  The  check  boxes  turn  options  on  (indicated  by  an  X)  and  off  The 
circular  radio  buttons  allow  the  user  to  select  from  a  set  of  mutually  exclusive  options. 

Another,  simple  form  of  a  dialog  box  is  called  a  message  box.  This  box  displays  one  or 
more  lines  of  text,  an  optional  icon  such  as  an  exclamation  point  or  an  asterisk,  and  one 
or  more  buttons  containing  the  words  OK,  Yes,  No,  or  Cancel  Programs  sometimes  use 
message  boxes  for  warnings  or  error  messages. 


The  MS-DOS  Executive 

Within  Windows,  the  MS-DOS  Executive  program  (shown  in  Figure  17-8)  serves  much  the 
same  function  as  the  COMMAND.COM  program  in  the  MS-DOS  environment. 

The  top  of  the  MS-DOS  Executive  client  area  displays  all  valid  disk  drives.  The  current 
disk  drive  is  highlighted.  Below  or  to  the  right  of  the  disk  drives  is  a  display  of  the  full  path 
of  the  current  directory.  Below  this  is  an  alphabetic  listing  of  all  subdirectories  in  the  cur¬ 
rent  directory,  followed  by  an  alphabetic  listing  of  all  files  in  the  current  directory.  Sub¬ 
directory  names  are  displayed  in  boldface  to  distinguish  them  from  filenames. 

The  user  can  change  the  current  drive  by  clicking  on  the  disk  drive  with  the  mouse  or  by 
pressing  Ctrl  and  the  key  corresponding  to  the  disk  drive  letter. 

To  change  to  one  of  the  parent  directories,  the  user  double-clicks  (clicks  the  mouse  button 
twice  in  succession)  on  the  part  of  the  text  string  corresponding  to  the  directory  name. 
Pressing  the  Backspace  key  moves  up  one  directory  level  toward  the  root  directory.  The 
user  can  also  change  the  current  directory  to  a  child  subdirectory  by  double-clicking  on 
the  subdirectory  name  in  the  list  or  by  pressing  the  Enter  key  when  the  cursor  highlight  is 
on  the  subdirectory  name.  In  addition,  the  menu  also  contains  an  option  for  changing  the 
current  directory. 
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Figure  1 7-8.  The  MS-DOS  Executive. 


The  user  can  run  a  program  by  double-clicking  on  the  program  filename,  by  pressing  the 
Enter  key  when  the  highlight  is  on  the  program  name,  or  by  selecting  it  from  a  menu. 

Other  menu  options  allow  the  user  to  display  the  file  and  subdirectory  lists  in  a  variety 
of  ways.  A  long  format  includes  the  same  information  displayed  by  the  MS-DOS  DIR  com¬ 
mand,  or  the  user  can  choose  to  display  a  select  group  of  files.  Menu  options  also  enable 
the  user  to  specify  whether  the  files  should  be  listed  in  alphabetic  order  by  filename,  by 
filename  extension,  or  by  date  or  size. 

The  remaining  options  on  the  MS-DOS  Executive  menu  allow  the  user  to  run  programs; 
copy,  rename,  and  delete  files;  format  a  floppy  disk;  change  a  volume  name;  make  a 
system  disk;  create  a  subdirectory;  and  print  a  text  file. 


other  Windows  Programs 

Windows  2.0  also  includes  a  number  of  application  and  utility  programs.  The  application 
programs  are  CALC  (a  calculator),  CALENDAR,  CARDFILE  (a  database  arranged  as  a 
series  of  index  cards),  CLOCK,  NOTEPAD,  PAINT  (a  drawing  and  painting  program), 
REVERSI  (a  game),  TERMINAL,  and  WRITE  (a  word  processor). 

The  utility  programs  include 

CLIPBRD.  This  program  displays  the  current  contents  of  the  Clipboard,  which  is  a  storage 
facility  that  allows  users  to  transfer  data  from  one  program  to  another. 
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CONTROL  The  Control  Panel  utility  allows  the  user  to  add  or  delete  font  files  and  printer 
drivers  and  to  change  the  following:  current  printer,  printer  output  port,  communications 
parameters,  date  and  time,  cursor  blink  rate,  screen  colors,  border  width,  mouse  double¬ 
click  time  and  options,  and  country-specific  information,  such  as  time  and  date  formats. 
The  Control  Panel  stores  much  of  this  information  in  the  file  named  WIN.INI  (Windows 
Initialization),  so  the  information  is  available  to  other  Windows  programs. 

PIFEDIT  The  PIF  editor  allows  the  user  to  create  or  modify  the  PIFs  that  contain  infor¬ 
mation  about  standard  applications  that  have  not  been  specially  designed  to  run  under 
Windows.  This  information  allows  Windows  to  adjust  the  environment  in  which  the 
program  runs. 

SPOOLER.  Windows  uses  the  print-spooler  utility  to  print  files  without  suspending  the 
operation  of  other  programs.  Most  printer-directed  output  from  Windows  programs  goes 
to  the  print  spooler,  which  then  prints  the  files  while  other  programs  run.  SPOOLER 
enables  the  user  to  change  the  priority  of  print  jobs  or  to  cancel  them. 


The  Structure  of  Windows 

When  programs  run  under  MS-DOS,  they  make  requests  of  the  operating  system  through 
MS-DOS  software  interrupts  (such  as  Interrupt  21H),  through  BIOS  software  interrupts,  or 
by  directly  accessing  the  machine  hardware. 

When  programs  run  under  Windows,  they  use  MS-DOS  function  calls  only  for  file  input 
and  output  and  (more  rarely)  for  executing  other  programs.  Windows  programs  do  not  use 
MS-DOS  function  calls  for  memory  management,  keyboard  input,  display  or  printer  out¬ 
put,  or  RS232  communications.  Nor  do  Windows  programs  use  BIOS  routines  or  direct 
access  to  the  hardware. 

Instead,  Windows  provides  application  programs  with  access  to  more  than  450  functions 
that  allow  programs  to  create  and  manipulate  windows  on  the  display;  use  menus,  dialog 
boxes,  and  scroll  bars;  display  text  and  graphics  within  the  client  area  of  a  window;  use 
the  printer  and  RS232  communications  port;  and  allocate  memory. 

The  Windows  modules 

The  functions  provided  by  Windows  are  largely  handled  by  three  main  modules  named 
KERNEL,  GDI,  and  USER.  The  KERNEL  module  is  responsible  for  scheduling  and  multi¬ 
tasking,  and  it  provides  functions  for  memory  management  and  some  file  I/O.  The  GDI 
module  provides  Windows’  Graphics  Device  Interface  functions,  and  the  USER  module 
does  everything  else. 

The  USER  and  GDI  modules,  in  turn,  call  functions  in  various  driver  modules  that  are  also 
included  with  Windows.  Drivers  control  the  display,  printer,  keyboard,  mouse,  sound, 
RS232  port,  and  timer.  In  most  cases,  these  driver  modules  access  the  hardware  of  the  com¬ 
puter  directly.  Windows  includes  different  driver  files  for  various  hardware  configurations. 
Hardware  manufacturers  can  also  develop  Windows  drivers  specifically  for  their  products. 
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A  block  diagram  showing  the  relationships  of  an  application  program,  the  KERNEL,  USER, 
and  GDI  modules,  and  the  driver  modules  is  shown  in  Figure  17-9.  The  figure  shows  each 
of  these  modules  as  a  separate  file — KERNEL,  USER,  and  GDI  have  the  extension  .EXE; 
the  driver  files  have  the  extension  .DRV.  Some  program  developers  install  Windows  with 
these  modules  in  separate  files,  as  in  Figure  17-9,  but  most  users  install  Windows  by 
running  the  SETUP  program  included  with  Windows. 

SETUP  combines  most  of  these  modules  into  two  larger  files  called  WIN200.BIN  and 
WIN200.OVL.  Printer  drivers  are  a  little  different  from  the  other  driver  files,  however, 
because  the  Windows  SETUP  program  does  not  include  them  in  WIN200.BIN  and 
WIN200.OVL.  The  name  of  the  driver  file  identifies  the  printer.  For  example,  IBMGRX.DRV 
is  a  printer  driver  file  for  the  IBM  Personal  Computer  Graphics  Printer. 


Figure  1 7-9.  A  simplified  block  diagram  showing  the  relationships  of  an  application  program,  Windows 
modules  (GDI,  USER,  and  KERNEL),  driver  modules,  and  system  hardware. 
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The  diagram  in  Figure  17-9  is  somewhat  simplified.  In  reality,  a  Windows  application 
program  can  also  make  direct  calls  to  the  KEYBOARD.DRV  and  SOUND.DRV  modules, 
and  USER.EXE  calls  the  DISPLAY.DRV  and  printer  driver  modules  directly.  The  GDI.EXE 
module  and  driver  modules  can  also  call  routines  in  KERNEL.EXE,  and  drivers  sometimes 
call  routines  in  SYSTEM.DRV. 

Also,  Figure  17-9  omits  the  various  font  files  provided  with  Windows,  the  WIN.INI  file 
that  contains  Windows  initialization  information  and  user  preferences,  and  the  files 
WINOLDAP.MOD  and  WINOLDAP.GRB,  which  Windows  uses  to  run  standard  MS-DOS 
applications. 

libraries  and  programs 

The  USER.EXE,  GDI.EXE,  and  KERNEL.EXE  files,  all  driver  files  with  the  extension  .DRV, 
and  all  font  files  with  the  extension  .FON  are  called  Windows  libraries  or,  sometimes, 
dynamic  link  libraries  to  distinguish  them  from  Windows  programs.  Programs  and 
libraries  both  use  a  file  format  called  the  New  Executable  format. 

From  the  user’s  perspective,  a  Windows  program  and  a  Windows  library  are  very  differ¬ 
ent.  The  user  cannot  run  a  Windows  library  directly:  Windows  loads  a  part  of  a  library  into 
memory  only  when  a  program  needs  to  use  a  function  that  the  library  provides. 

The  user  can  also  run  multiple  instances  of  the  same  Windows  program.  Windows  uses 
the  same  code  segments  for  the  different  instances  but  creates  a  unique  data  segment  for 
each.  Windows  never  runs  multiple  instances  of  a  Windows  library. 

From  the  programmer’s  perspective,  a  Windows  program  is  a  task  that  creates  and 
manages  windows  on  the  display.  Libraries  are  modules  that  assist  the  task.  A  programmer 
can  write  additional  library  modules,  which  one  or  more  programs  can  use.  For  the  devel¬ 
oper,  one  important  distinction  between  programs  and  libraries  is  that  a  Windows  library 
does  not  have  its  own  stack;  instead,  the  library  uses  the  stack  of  the  program  that  calls 
the  routine  in  the  library. 

The  New  Executable  format  used  for  both  programs  and  libraries  gives  Windows  much 
more  information  about  the  module  than  is  provided  by  the  current  MS-DOS  .EXE  format. 
In  particular,  the  module  contains  information  that  allows  Windows  to  make  links  be¬ 
tween  program  modules  and  library  modules  when  a  program  is  run. 

When  a  module  (such  as  a  library)  contains  functions  that  can  be  called  from  another 
module  (such  as  a  program),  the  functions  are  said  to  be  exported  from  the  module  that 
contains  them.  Each  exported  function  in  a  module  is  identified  either  by  a  name  (gener¬ 
ally  the  name  of  the  function)  or  by  an  ordinal  (positive)  number.  A  list  of  all  exported 
functions  in  a  module  is  included  in  the  New  Executable  format  header  section  of  the 
module. 

Conversely,  when  a  module  (such  as  a  program)  contains  code  that  calls  a  function  in 
another  module  (such  as  a  library),  the  function  is  said  to  be  imported  to  the  module  that 
makes  the  call.  This  call  appears  in  the  .EXE  file  as  an  unresolved  reference  to  an  external 
function.  The  New  Executable  format  identifies  the  module  and  the  function  name  or 
ordinal  number  that  the  call  references. 
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When  Windows  loads  a  program  or  a  library  into  memory,  it  must  resolve  all  calls  the 
module  makes  to  functions  in  other  modules.  Windows  does  this  by  inserting  the  ad¬ 
dresses  of  the  functions  into  the  code — a  process  called  dynamic  linking. 

For  example,  many  Windows  programs  use  the  function  TextOut  to  display  text  in  the 
client  area.  In  the  code  segment  of  the  program’s  .EXE  file,  a  call  to  TextOut  appears  as  an 
unresolved  far  (intersegment)  call.  The  code  segment’s  relocation  table  shows  that  this  call 
is  to  an  imported  function  in  the  GDI  module  identified  by  the  ordinal  number  33.  The 
header  section  of  the  GDI  module  lists  TextOut  as  an  exported  function  with  the  ordinal 
number  33.  When  Windows  loads  the  program,  it  resolves  all  references  to  TextOut  by 
inserting  the  address  of  the  function  into  the  program’s  code  segment  in  each  place 
where  TextOut  is  called. 

Although  Windows  programs  reference  many  functions  that  are  exported  from  the  stan¬ 
dard  Windows  libraries,  Windows  programs  also  often  include  at  least  one  exported  func¬ 
tion,  called  a  window  function.  While  the  program  is  running,  Windows  calls  this  function 
to  pass  messages  to  the  program’s  window.  See  The  Structure  of  a  Windows  Program 
below. 


Memory  Management 

Windows’  memory  management  is  based  on  the  segmented-memory  architecture  of 
the  Intel  8086  family  of  microprocessors.  The  memory  space  controlled  by  Windows  is 
divided  into  segments  of  various  lengths.  Windows  uses  separate  segments  for  nearly 
everything  kept  in  memory — such  as  the  code  and  data  segments  of  programs  and 
libraries — and  for  resources,  such  as  fonts  and  bitmaps. 

Windows  programs  and  libraries  contain  one  or  more  code  segments,  which  are  usually 
both  movable  and  discardable.  Windows  can  move  a  code  segment  in  memory  in  order  to 
consolidate  free  memory  space.  It  can  also  discard  a  code  segment  from  memory  and  later 
reload  the  code  segment  from  the  program’s  or  library’s  .EXE  file  when  it  is  needed  again. 
This  capability  is  called  demand  loading. 

Windows  programs  usually  contain  only  one  data  segment;  Windows  libraries  are  limited 
to  one  data  segment.  In  most  cases,  Windows  can  move  data  segments  in  memory.  How¬ 
ever,  it  cannot  usually  discard  data  segments,  because  they  can  contain  data  that  changes 
after  the  program  begins  executing.  When  a  user  runs  multiple  copies  of  a  program,  the 
different  instances  share  the  same  code  segments  but  have  separate  data  segments. 

The  use  of  movable  and  discardable  segments  allows  Windows  to  run  several  large 
programs  in  a  memory  space  that  might  be  inadequate  for  even  one  of  the  programs  if  the 
entire  program  were  kept  in  memory,  as  is  typical  under  MS-DOS  without  Windows.  The 
ability  of  Windows  to  use  memory  in  this  way  is  called  memory  overcommitment. 

The  moving  and  discarding  of  code  segments  requires  Windows  to  make  special  provi¬ 
sions  so  that  intersegment  calls  continue  to  reference  the  correct  address  when  a  code 
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segment  is  moved.  These  provisions  are  another  part  of  dynamic  linking.  When  Windows 
resolves  a  far  call  from  one  code  segment  to  a  function  in  another  code  segment  that  is 
movable  and  discardable,  the  call  actually  references  a  fixed  area  of  memory.  This  fixed 
area  of  memory  contains  a  small  section  of  code  called  a  thunk.  If  the  code  segment  con¬ 
taining  the  function  is  currently  in  memory,  the  thunk  simply  jumps  to  the  function.  If  the 
code  segment  with  the  function  is  not  currently  in  memory,  the  thunk  calls  a  loader  that 
loads  the  segment  into  memory.  This  process  is  called  dynamic  loading.  When  Windows 
moves  or  discards  a  code  segment,  it  must  alter  the  thunks  appropriately. 

Windows  and  Windows  programs  generally  reference  data  structures  stored  in  Windows’ 
memory  space  by  using  l6-bit  unsigned  integers  known  as  handles.  The  data  structure  that 
a  handle  references  can  be  movable  and  discardable,  so  when  Windows  or  the  Windows 
program  needs  to  access  the  data  directly,  it  must  lock  the  handle  to  cause  the  data  to 
become  fixed  in  memory.  The  function  that  locks  the  segment  returns  a  pointer  to  the 
program. 

During  the  time  the  handle  is  locked,  Windows  cannot  move  or  discard  the  data.  The  data 
can  then  be  referenced  directly  with  the  pointer.  When  Windows  (or  the  Windows  pro¬ 
gram)  finishes  using  the  data,  it  unlocks  the  segment  so  that  it  can  be  moved  (or  in  some 
cases  discarded)  to  free  up  memory  space  if  necessary. 

Programmers  can  choose  to  allocate  nonmovable  data  segments,  but  the  practice  is  not 
recommended,  because  Windows  cannot  relocate  the  segments  to  make  room  for  seg¬ 
ments  required  by  other  programs. 


The  Structure  of  a  Windows  Program 

During  development,  a  Windows  program  includes  several  components  that  are  combined 
later  into  a  single  executable  file  with  the  extension  .EXE  for  execution  under  Windows. 
Although  the  Windows  executable  file  has  the  same  .EXE  filename  extension  as  MS-DOS 
executable  files,  the  format  is  different.  Among  other  things,  the  New  Executable  format 
includes  Windows-specific  information  required  for  dynamic  linking  and  the  discarding 
and  reloading  of  the  program’s  code  segments. 

Programmers  generally  use  C,  Pascal,  or  assembly  language  to  create  applications  specially 
designed  to  run  under  Windows.  Also  required  are  several  header  files  and  development 
tools,  which  are  included  in  the  Microsoft  Windows  Software  Development  Kit. 

The  Microsoft  Windows  Software  Development  Kit 

The  Windows  Software  Development  Kit  contains  reference  material,  a  special  linker 
(LINK4),  the  Windows  Resource  Compiler  (RC),  special  versions  of  the  SYMDEB  and 
CodeView  debuggers,  header  files,  and  several  programs  that  aid  development  and  testing. 
These  programs  include 

•  DIALOG:  Used  for  creating  dialog  boxes. 

•  ICONEDIT:  Used  for  creating  a  program’s  icon,  customized  cursors,  and  bitmap 
images. 
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•  FONTEDIT:  Used  for  creating  customized  fonts  derived  from  an  existing  font  file 
with  the  extension  .FNT. 

•  HEAPWALK:  Used  for  displaying  the  organization  of  code  and  data  segments  in 
Windows’  memory  space  and  for  testing  programs  under  low  memory  conditions. 

•  SHAKER:  Used  for  randomly  allocating  memory  to  force  segment  movement  and 
discarding.  SHAKER  tests  a  program’s  response  to  movement  in  memory  and  is  useful 
for  exposing  program  bugs  involving  pointers  to  unlocked  segments. 

The  Windows  Software  Development  Kit  also  provides  several  include  and  header  files 
that  contain  declarations  of  all  Windows  functions,  definitions  of  many  macro  identifiers 
that  the  programmer  can  use,  and  structure  definitions.  Import  libraries  included  in  the 
kit  allow  LINK4  to  resolve  calls  to  Windows  functions  and  to  prepare  the  program’s  .EXE 
file  for  dynamic  linking. 

Work  with  the  Windows  Software  Development  Kit  requires  one  of  the  following  com¬ 
pilers  or  assemblers: 

•  Microsoft  C  Compiler  version  4.0  or  later 

•  Microsoft  Pascal  Compiler  version  3-31  or  later 

•  Microsoft  Macro  Assembler  version  4.0  or  later 

Other  software  manufacturers  also  provide  compilers  that  are  suitable  for  compiling 
Windows  programs. 

Components  of  a  Windows  program 

The  discussion  in  this  section  is  illustrated  by  a  program  called  SAMPLE,  which  displays 
the  word  Windows  in  its  client  area.  In  response  to  a  menu  selection,  the  program 


Figure  1 7-10.  A  display  produced  by  the  example  program  SAMPLE. 
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displays  this  text  in  any  of  the  three  vector  fonts  —  Script,  Modern,  and  Roman — that  are 
included  with  Windows.  Sometimes  also  called  stroke  or  graphics  fonts,  these  vector  fonts 
are  defined  by  a  series  of  line  segments,  rather  than  by  the  pixel  patterns  that  make  up  the 
more  common  raster  fonts.  The  SAMPLE  program  picks  a  font  size  that  fits  the  client  area. 

Figure  17-10  shows  several  instances  of  this  program  running  under  Windows. 

Five  separate  files  go  into  the  making  of  this  program: 

1.  Source-code  file:  This  is  the  main  part  of  the  program,  generally  written  in  C,  Pascal, 
or  assembly  language.  The  SAMPLE  program  was  written  in  C,  which  is  the  most 
popular  language  for  Windows  programs  because  of  its  flexibility  in  using  pointers 
and  structures.  The  SAMPLE.C  source-code  file  is  shown  in  Figure  17-11. 

/*  SAMPLE.C  —  Demonstration  Windows  Program  */ 


#include  <windows.h> 
#include  "sample. h" 


long  FAR  PASCAL  WndProc  (HWND,  unsigned,  WORD,  LONG)  ; 


int  PASCAL  WinMain  (hinstance,  hPrevInstance,  IpszCmdLine^  nCmdShow) 
HANDLE  hinstance,  hPrevInstance  ; 

LPSTR  IpszCmdLine  ; 

int  nCmdShow  ; 


{ 

WNDCLASS  wndclass  ; 

HWND  hWnd  ; 

MSG  msg  ; 

static  char  szAppName  []  =  "Sample"  ; 


/* - ♦/ 

/*  Register  the  Window  Class  */ 
/* - */ 


if  ( IhPrevInstance) 

{ 

wndclass . style 
wndclass . IpfnWndProc 
wndclass . cbClsExtra 
wndclass . cbWndExtra 
wndclass .hinstance 
wndclass .hicon 
wndclass . hCursor 
wndclass . hbrBackground 
wndclass . IpszMenuName 
wndclass . IpszClassName 


=  CS_HREDRAW  1  CS_VREDRAW  ; 

=  WndProc  ; 

=  0  ; 

=  0  ; 

=  hinstance  ; 

=  NULL  ; 

=  LoadCursor  (NULL,  I DC-ARROW )  ; 

=  GetStockObject  (WHITE-BRUSH)  ; 
=  szAppName  ; 

=  szAppName  ; 


RegisterClass  (Swndclass)  ; 
} 


Figure  1 7-11.  The  SAMPLE.  C  source  code. 
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/* - */ 

/*  Create  the  window  and  display  it  */ 
/* - */ 


hWnd  =  CreateWindow  (szAppName,  "Demonstration  Windows  Program", 
WS_OVERLAPPEDWINDOW, 

(int)  CW_USEDEFAULT,  0, 

(int)  CW_USEDEFAULT,  0, 

NULL,  NULL,  hinstance,  NULL)  ; 

ShowWindow  (hWnd,  nCmdShow)  ; 

UpdateWindow  (hWnd)  ; 


/* 


*/ 


/*  Stay  in  message  loop  until  a  WM_QUIT  message  */ 
/* - */ 


while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 
DispatchMessage  (&msg)  ; 

} 

return  msg.wParam  ; 

} 


long  FAR  PASCAL  WndProc  (hWnd,  iMessage,  wParam,  iParam) 

HWND  hWnd  ; 

unsigned  iMessage  ; 

WORD  wParam  ; 

LONG  IParam  ; 

{ 

PAINTSTRUCT  ps  ; 

HFONT  hFont  ; 

HMENU  hMenu  ; 

static  short  xClient,  yClient,  nCurrentFont  =  IDM_SCRIPT  ; 
static  BYTE  cFamily  []  =  {  FF_SCRIPT,  FF_MODERN,  FF_ROMAN  }  ; 
static  char  *szFace  []  =  {  "Script",  "Modern",  "Roman"  }  ; 

switch  (iMessage) 

{ 


/* - */ 

/*  WM_COMMAND  message:  Change  checkmarked  font  */ 
/* - 


case  WM_COMMAND: 

hMenu  =  GetMenu  (hWnd)  ; 

CheckMenuItem  (hMenu,  nCurrentFont,  MF_UNCHECKED)  ; 
nCurrentFont  =  wParam  ; 

CheckMenuItem  (hMenu,  nCurrentFont,  MF_CHECKED)  ; 
InvalidateRect  (hWnd,  NULL,  TRUE)  ; 
break  ; 


Figure  17-11.  Continued. 
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/* - */ 

/*  WM_SIZE  message:  Save  dimensions  of  window  */ 
/* - */ 

case  WM_SIZE: 

xClient  =  LOWORD  (IParam)  ; 
yClient  =  HIWORD  (IParam)  ; 
break  / 


/* - */ 

/*  WM_PAINT  message:  Display  "Windows"  in  Script  */ 

/* - */ 

case  WM_PAINT: 

BeginPaint  (hWnd,  &ps)  ; 

hFont  =  CreateFont  (yClient,  xClient  /  8, 

0,  0,  400,  0,  0,  0,  OEM_CHARSET, 
OUT_STROKE_PRECIS,  OUT_STROKE_PRECIS, 
DRAFT_QUALITY,  (BYTE)  VARIABLE_PITCH  1 

cFamily  [nCurrentFont  -  IDM_SCRIPT] , 

szFace  [nCurrentFont  -  IDM_SCRIPT] )  ; 

hFont  =  SelectObject  (ps.hdc,  hFont)  ; 

TextOut  (ps.hdc,  0,  0,  "Windows",  7)  ; 

DeleteObject  (SelectObject  (ps.hdc,  hFont))  ; 

EndPaint  (hWnd,  &ps)  ; 

break  ; 

/* - */ 

/*  WM_DESTROY  message:  Post  Quit  message  */ 

/* - */ 

case  WM_DESTROY: 

PostQuitMessage  (0)  ; 

break  ; 


/* - */ 

/*  Other  messages:  Do  default  processing  */ 
/* - */ 


default : 

return  DefWindowProc  (hWnd,  iMessage,  wParam,  IParam)  ; 

} 

return  OL  ; 

} 

Figure  17-11.  Continued. 
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2.  Resource  script:  The  resource  script  is  an  ASCII  file  that  generally  has  the  extension 
.RC.  This  file  contains  definitions  of  menus,  dialog  boxes,  string  tables,  and  keyboard 
accelerators  used  by  the  program.  The  resource  script  can  also  reference  other  files 
that  contain  icons,  cursors,  bitmaps,  and  fonts  in  binary  form,  as  well  as  other  read¬ 
only  data  defined  by  the  programmer.  When  a  program  is  running,  Windows  loads 
resources  into  memory  only  when  they  are  needed  and  in  most  cases  can  discard 
them  if  additional  memory  space  is  required. 

SAMPLE.RC,  the  resource  script  for  the  SAMPLE  program,  is  shown  in  Figure  17-12;  it 
contains  only  the  definition  of  the  menu  used  in  the  program. 

#include  "sample. h” 

Sample  MENU 
BEGIN 

POPUP  "STypeface” 

BEGIN 

MENUITEM  "SScript”,  IDM_SCRIPT,  CHECKED 
MENU ITEM  "SModern”,  IDM_MODERN 
MENUITEM  ”& Roman”,  IDM_ROMAN 

END 

END 

Figure  1 7-12.  The  resource  script for  the  SAMPLE  program . 

3.  Header  (or  include  file:  This  file,  with  the  extension  .H,  can  contain  definitions  of 
constants  or  macros,  as  is  customary  in  C  programming.  For  Windows  programs,  the 
header  file  also  reconciles  constants  used  in  both  the  resource  script  and  the  pro¬ 
gram  source-code  file.  For  example,  in  the  SAMPLE.RC  resource  script,  each  item  in 
the  pop-up  menu  {Script,  Modern,  and  Romari)  also  includes  an  identifier — 
IDM_SCRIPT,  IDM_MODERN,  and  IDM_ROMAN,  respectively.  These  identifiers 
are  merely  numbers  that  Windows  uses  to  notify  the  program  of  the  user’s  selection 
of  a  menu  item.  The  same  names  are  used  to  identify  the  menu  selection  in  the  C 
source-code  file.  And,  because  both  the  resource  compiler  and  the  source-code  com¬ 
piler  must  have  access  to  these  identifiers,  the  header  file  is  included  in  both  the 
resource  script  and  the  source-code  file. 

The  header  file  for  the  SAMPLE  program,  SAMPLE.H,  is  shown  in  Figure  17-13. 

#define  IDM_SCRIPT  1 
tdefine  IDM_MODERN  2 
#define  IDM_ROMAN  3 

Figure  17-13.  The  SAMPLE.H  header  file. 

4.  Module-definition  file:  The  module-definition  file  generally  has  a  .DEF  extension. 
The  Windows  linker  uses  this  file  in  creating  the  executable  .EXE  file.  The  module- 
definition  file  specifies  various  attributes  of  the  program’s  code  and  data  segments, 
and  it  lists  all  imported  and  exported  functions  in  the  source-code  file.  In  large  pro¬ 
grams  that  are  divided  into  multiple  code  segments,  the  module-definition  file  allows 
the  programmer  to  specify  different  attributes  for  each  code  segment. 
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The  module-definition  file  for  the  SAMPLE  program  is  named  SAMPLE.DEF  and  is 
shown  in  Figure  17-14. 


NAME 

DESCRIPTION 

STUB 

CODE 

DATA 

HEAPSIZE 

STACKS I ZE 

EXPORTS 


SAMPLE 

'Demonstration  Windows  Program' 
'WINSTUB.EXE* 

MOVABLE 

MOVABLE  MULTIPLE 

1024 

4096 

WndProc 


Figure  1 7-14.  The  SAMPLE. DEF  module-definition  file. 


5.  Make  file:  To  facilitate  construction  of  the  executable  file  from  these  different  com¬ 
ponents,  Windows  programmers  often  use  the  MAKE  program  to  compile  only  those 
files  that  have  changed  since  the  last  time  the  program  was  linked.  To  do  this,  the 
programmer  first  creates  an  ASCII  text  file  called  a  make  file.  By  convention,  the 
make  file  has  no  extension. 

The  make  file  for  the  SAMPLE  program  is  named  SAMPLE  and  is  shown  in  Figure 
17-15.  The  programmer  can  create  the  SAMPLE.EXE  executable  file  by  executing 

OMAKE  SAMPLE  <Enter> 

A  make  file  often  contains  several  sections,  each  beginning  with  a  target  filename, 
followed  by  a  colon  and  one  or  more  dependent  filenames,  such  as 

sample. obj  :  sample, c  sample. h 

If  either  or  both  the  SAMPLE.C  and  SAMPLE.H  files  have  a  later  creation  time  than 
SAMPLE.OBJ,  then  MAKE  runs  the  program  or  programs  listed  immediately  below. 
In  the  case  of  the  SAMPLE  make  file,  the  program  is  the  C  compiler,  and  it  compiles 
the  SAMPLE.C  source  code: 


cl  -c  -Gsw  -W2  -Zdp  sample. c 

Thus,  if  the  programmer  changes  only  one  of  the  several  files  used  in  the  develop¬ 
ment  of  SAMPLE,  then  running  MAKE  ensures  that  the  executable  file  is  brought  up 
to  date,  while  carrying  out  only  the  required  steps. 


sample . obj 
cl  -c 


;  sample. c  sample. h 
-Gsw  -W2  -Zdp  sample. c 


sample . res 
rc  -r 


:  sample. rc  sample. h 
sample . rc 


sample.exe  :  sample. obj  sample. def  sample. res 

link4  sample,  /align: 16,  /map  /line,  slibw,  sample 
rc  sample. res 
mapsym  sample 

Figure  1 7-15.  The  make file  for  the  SAMPLE  program. 
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Construction  of  a  Windows  program 

The  make  file  shows  the  steps  that  create  a  program’s  .EXE  file  from  the  various 

components: 

1 .  Compiling  the  source-code  file: 

cl  -c  -Gsw  -W2  -Zdp  sample. c 

This  step  uses  the  CL.EXE  C  compiler  to  create  a  .OBJ  object-module  file.  The  com¬ 
mand  line  switches  are 

-  -c:  Compiles  the  program  but  does  not  link  it.  Windows  programs  must  be  linked 
with  Windows’  LINK4  linker,  rather  than  with  the  LINK  program  the  C  compiler 
would  normally  invoke. 

-  -Gsw:  Includes  two  switches,  -Gs  and  -Gw.  The  -Gs  switch  removes  stack  checks 
from  the  program.  The  -Gw  switch  inserts  special  prologue  and  epilogue  code  in 
all  far  functions  defined  in  the  program.  This  special  code  is  required  for  Win¬ 
dows’  memory  management. 

-  -W2:  Compiles  with  warning  level  2.  This  is  the  highest  warning  level,  and  it  causes 
the  compiler  to  display  messages  for  conditions  that  may  be  acceptable  in  normal  C 
programs  but  that  can  cause  serious  errors  in  a  Windows  program. 

-  -Zdp:  Includes  two  switches,  -Zd  and  -Zp.  The  -Zd  switch  includes  line  numbers 
in  the  .OBJ  file — helpful  for  debugging  at  the  source-code  level.  The  -Zp  switch 
packs  structures  on  byte  boundaries.  The  -Zp  switch  is  required,  because  data 
structures  used  within  Windows  are  in  a  packed  format. 

2.  Compiling  the  resource  script: 

rc  -r  sample. rc 

This  step  runs  the  resource  compiler  and  converts  the  ASCII  .RC  resource  script  into  a 
binary  .RES  form.  The  -r  switch  indicates  that  the  resource  script  should  be  compiled 
but  the  resources  should  not  yet  be  added  to  the  program’s  .EXE  file. 

3.  Linking  the  program: 

link4  sample,  /align: 16,  /map  /line,  slibw,  sample 

This  step  uses  the  special  Windows  linker,  LINK4.  The  first  parameter  listed  is  the 
name  of  the  .OBJ  file.  The  /align:  l6  switch  instructs  LINK4  to  align  segments  in  the 
.EXE  file  on  l6-byte  boundaries.  The  /map  and  /line  switches  cause  LINK4  to  create  a 
.MAP  file  that  contains  program  line  numbers — again,  useful  for  debugging  source 
code.  Next,  slibw  is  a  reference  to  the  SLIBW.LIB  file,  which  is  an  import  library  that 
contains  module  names  and  ordinal  numbers  for  all  Windows  functions.  The  last 
parameter,  sample,  is  the  program’s  module-definition  file,  SAMPLE.DEF. 

4.  Adding  the  resources  to  the  .EXE  file: 

rc  sample. res 
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This  step  runs  the  resource  compiler  a  second  time,  using  the  compiled  resource  file, 
SAMPLE.RES.  This  time,  the  resource  compiler  adds  the  resources  to  the  .EXE  file. 


Figure  1 7-16.  A  block  diagram  showing  the  creation  of  a  Windows  .EXE file. 
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5.  Creating  a  symbol  (.SYM)  file  from  the  linker’s  map  (.MAP)  file: 

mapsym  sample 

This  step  is  required  for  symbolic  debugging  with  SYMDEB. 

Figure  17-16  on  the  preceding  page  shows  how  the  various  components  of  a  Windows  pro¬ 
gram  fit  into  the  creation  of  a  .EXE  file. 

Program  initialization 

The  SAMPLE.C  program  shown  in  Figure  17-11  contains  some  code  that  appears  in  almost 
every  Windows  program.  The  statement 

#include  <windows.h> 

appears  at  the  top  of  every  Windows  source-code  file  written  in  C.  The  WINDOWS.H  file, 
provided  with  the  Microsoft  Windows  Software  Development  Kit,  contains  templates  for 
all  Windows  functions,  structure  definitions,  and  #define  statements  for  many  mnemonic 
identifiers. 

Some  of  the  variable  names  in  SAMPLE.C  may  look  unusual  to  C  programmers  because 
they  begin  with  a  prefix  notation  that  denotes  the  data  type  of  the  variable.  Windows 
programmers  are  encouraged  to  use  this  type  of  notation.  Some  of  the  more  common 
prefixes  are 


Prefix 

Dataiype 

i  or  n 

Integer  (l6-bit  signed  integer) 

w 

Word  (l6-bit  unsigned  integer) 

1 

Long  (32-bit  signed  integer) 

dw 

Doubleword  (32-bit  unsigned  integer) 

h 

Handle  (l6-bit  unsigned  integer) 

sz 

Null-terminated  string 

Ipsz 

Long  pointer  to  null-terminated  string 

Ipfn 

Long  pointer  to  a  function 

The  program’s  entry  point  (following  some  startup  code)  is  the  WinMain  function, 
which  is  passed  the  following  parameters:  a  handle  to  the  current  instance  of  the 
program  (hinstance),  a  handle  to  the  most  recent  previous  instance  of  the  program 
(hPrevInstance),  a  long  pointer  to  the  program’s  command  line  (IpszCmdLine),  and  a 
number  (nCmdShow)  that  indicates  whether  the  program  should  initially  be  displayed  as  a 
normally  sized  window  or  as  an  icon. 

The  first  job  SAMPLE  performs  in  the  WinMain  function  is  to  register  a  window  class — a 
structure  that  describes  characteristics  of  the  windows  that  will  be  created  in  the  class. 
These  characteristics  include  background  color,  the  type  of  cursor  to  be  displayed  in  the 
window,  the  window’s  initial  menu  and  icon,  and  the  window  function  (the  structure 
member  called  IpfnWndProc). 
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Multiple  instances  of  a  program  can  share  the  same  window  class,  so  SAMPLE  registers  the 
window  class  only  for  the  first  instance  of  the  program: 

if  ( ! hPrevInstance) 


wndclass . style  = 
wndclass . IpfnWndProc  = 
wndclass . cbClsExtra  = 
wndclass . cbWndExtra  = 
wndclass . hinstance  = 
wndclass .hicon  = 
wndclass .hCursor  = 
wndclass .hbrBackground  = 
wndclass . IpszMenuName  = 
wndclass . IpszClassName  = 


CS_HREDRAW  !  CS_VREDRAW  ; 
WndProc  ; 

0  ; 

0  ; 

hinstance  ; 

NULL  ; 

LoadCursor  (NULL,  IDC_ARROW)  ; 
GetStockObject  (WHITE_BRUSH)  ; 
szAppName  ; 
szAppName  ; 


RegisterClass  (&wndclass)  ; 

} 

The  SAMPLE  program  then  creates  a  window  using  the  CreateWindow  call,  displays  it  to 
the  screen  by  calling  ShowWindow,  and  updates  the  client  area  by  calling  UpdateWindow: 

hWnd  =  CreateWindow  (szAppName,  "Demonstration  Windows  Program", 

WS_OVERLAPPEDWINDOW, 

(int)  CW_USEDEFAULT,0, 

(int)  CW_USEDEFAULT,0, 

NULL,  NULL,  hinstance,  NULL)  ; 

ShowWindow  (hWnd,  nCmdShow)  ; 

UpdateWindow  (hWnd)  ; 

The  first  parameter  to  CreateWindow  is  the  name  of  the  window  class.  The  second  param¬ 
eter  is  the  actual  text  that  appears  in  the  window’s  title  bar.  The  third  parameter  is  the  style 
of  the  window— in  this  case,  the  WINDOWS.H  identifier  WS_OVERLAPPEDWINDOW. 
The  WS_OVERLAPPEDWINDOW  is  the  most  common  window  style.  The  fourth  through 
seventh  parameters  specify  the  initial  position  and  size  of  the  window.  The  identifier 
CW_USEDEFAULT  tells  Windows  to  position  and  size  the  window  according  to  the  default 
rules. 

After  creating  and  displaying  a  Window,  the  SAMPLE  program  enters  a  piece  of  code 
called  the  message  loop: 

while  (GetMessage  (&msg,  NULL,  0,  0)) 

{ 

TranslateMessage  (&msg)  ; 

Dispat chMessage  (&msg)  ; 


return  msg.wParam  ; 

This  loop  continues  to  execute  until  the  GetMessage  call  returns  zero.  When  that  happens, 
the  program  instance  terminates  and  the  memory  required  for  the  instance  is  freed. 
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The  Windows  messaging  system 

Interactive  programs  written  for  the  normal  MS-DOS  environment  generally  obtain  user 
input  only  from  the  keyboard,  using  either  an  MS-DOS  or  a  ROM  BIOS  software  interrupt 
to  check  for  keystrokes.  When  the  user  types  something,  such  programs  act  on  the  key¬ 
stroke  and  then  return  to  wait  for  the  next  keystroke. 

Programs  written  for  Windows,  however,  can  receive  user  input  from  a  variety  of  sources, 
including  the  keyboard,  the  mouse,  the  Windows  timer,  menus,  scroll  bars,  and  controls, 
such  as  buttons  and  edit  boxes. 

Moreover,  a  Windows  program  must  be  informed  of  other  events  occurring  within  the 
system.  For  instance,  the  user  of  a  Windows  program  might  choose  to  make  its  window 
smaller  or  larger.  Windows  must  make  the  program  aware  of  this  change  so  that  the  pro¬ 
gram  can  adjust  its  screen  output  to  fit  the  new  window  size.  Thus,  for  example,  if  a  Win¬ 
dows  program  is  minimized  as  an  icon  and  the  user  maximizes  its  window  to  fill  the  full 
screen,  Windows  must  inform  the  program  that  the  size  of  the  client  area  has  changed 
and  needs  to  be  re-created. 

Windows  carries  out  this  job  of  keeping  a  program  informed  of  other  events  through  the 
use  of  formatted  messages.  In  effect,  Windows  sends  these  messages  to  the  program.  The 
Windows  program  receives  and  acts  upon  the  messages. 

This  messaging  makes  the  relationship  between  Windows  and  a  Windows  program  much 
different  from  the  relationship  between  MS-DOS  and  an  MS-DOS  program.  Whereas 
MS-DOS  does  not  provide  information  until  a  program  requests  it  through  an  MS-DOS 
function  call,  Windows  must  continually  notify  a  program  of  all  the  events  that  affect  its 
window. 

Window  messages  can  be  separated  into  two  major  categories:  queued  and  nonqueued. 

Queued  messages  are  similar  to  the  keyboard  information  an  MS-DOS  program  obtains 
from  MS-DOS.  When  the  Windows  user  presses  a  key  on  the  keyboard,  moves  the  mouse, 
or  presses  one  of  the  mouse  buttons,  Windows  saves  information  about  the  event  (in  the 
form  of  a  data  structure)  in  the  system  message  queue.  Each  message  is  destined  for  a  par¬ 
ticular  window  in  a  particular  instance  of  a  Windows  program.  Windows  therefore  deter¬ 
mines  which  window  should  get  the  information  and  then  places  the  message  in  the 
instance’s  own  message  queue. 

A  Windows  program  retrieves  information  from  its  queue  in  the  message  loop: 

while  (GetMessage  (&msg,  NULL,  0,  0) ) 

{ 

TranslateMessage  (&msg)  ; 

DispatchMessage  (&msg)  ; 

} 

The  msg  variable  is  a  structure.  During  the  GetMessage  call,  Windows  fills  in  the  fields  of 
this  structure  with  information  about  the  message.  The  fields  are  as  follows: 
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•  hwnd\  The  handle  for  the  window  that  is  to  receive  the  message. 

•  Message:  A  numeric  code  identifying  the  type  of  message  (for  example,  keyboard 
or  mouse). 

•  wParam:  A  l6-bit  value  containing  information  specific  to  the  message.  See  The 
Windows  Messages  below. 

•  iParam:  A  32-bit  value  containing  information  specific  to  the  message. 

•  time:  The  time,  in  milliseconds,  that  the  message  was  placed  in  the  queue.  The  time 
is  a  32-bit  value  relative  to  the  time  at  which  the  current  Windows  session  began. 

•  pt.x:  The  horizontal  coordinate  of  the  mouse  cursor  at  the  time  the  event  occurred. 

•  pt.y:  The  vertical  coordinate  of  the  mouse  cursor  at  the  time  the  event  occurred. 

GetMessage  always  returns  a  nonzero  value  except  when  it  receives  a  quit  message.  The 
quit  message  causes  the  message  loop  to  end.  The  program  should  then  terminate  and 
return  control  to  Windows. 

Within  the  message  loop,  the  TranslateMessage  function  translates  physical  keystrokes  into 
character-code  messages.  Windows  places  these  translated  messages  into  the  program’s 
message  queue. 

The  DispatchMessage  function  essentially  makes  a  call  to  the  window  function  of  the  win¬ 
dow  specified  by  the  hwnd  field.  This  window  function  (WndProc  in  SAMPLE)  is  indicated 
in  the  IpfnWndProc  field  of  the  window  class  structure. 

When  DispatchMessage  passes  the  message  to  the  window  function,  Windows  uses  the 
first  four  fields  of  the  message  structure  as  parameters  to  the  function.  The  window  func¬ 
tion  can  then  process  the  message.  In  SAMPLE,  for  instance,  the  four  fields  passed  to 
WndProc  are  humd  (the  handle  to  the  window).  Message  (the  numeric  message  iden¬ 
tifier),  wParam,  and  IParam.  Although  Windows  does  not  pass  the  time  and  mouse- 
position  information  fields  as  parameters  to  the  window  function,  this  information  is 
available  through  the  Windows  functions  GetMessageTime  and  GetMessagePos. 

A  Windows  program  obtains  only  a  few  specific  types  of  messages  through  its  message 
queue.  These  are  keyboard  messages,  mouse  messages,  timer  messages,  the  paint  message 
that  tells  the  program  it  must  re-create  the  client  area  of  its  window,  and  the  quit  message 
that  tells  the  program  it  is  being  terminated. 

In  addition  to  the  queued  messages,  however,  a  program’s  window  function  also  receives 
many  nonqueued  messages.  Windows  sends  these  nonqueued  messages  by  bypassing  the 
message  loop  and  calling  the  program’s  window  function  directly. 

Many  of  these  nonqueued  messages  are  derived  from  queued  messages.  For  example, 
when  the  user  clicks  the  mouse  on  the  menu  bar,  a  mouse-click  message  is  placed  in  the 
program’s  message  queue.  The  GetMessage  function  retrieves  the  message  and  the  Dis¬ 
patchMessage  function  sends  it  to  the  program’s  window  function.  However,  because  this 
mouse  message  affects  a  nonclient  area  of  the  window  (an  area  outside  the  window’s  cli¬ 
ent  area),  the  window  function  normally  does  not  process  it.  Instead,  the  function  passes 
the  message  back  to  Windows.  In  this  example,  the  message  tells  Windows  to  invoke  a 
pop-up  menu.  Windows  calls  up  the  menu  and  then  sends  the  window  function  several 
nonqueued  messages  to  inform  the  program  of  this  action. 
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A  Windows  program  is  thus  message  driven.  Once  a  program  reaches  the  message  loop, 
it  acts  only  when  the  window  function  receives  a  message.  And,  although  a  program 
receives  many  messages  that  affect  the  window,  the  program  usually  processes  only  some 
of  them,  sending  the  rest  to  Windows  for  normal  default  processing. 

The  Windows  messages 

Windows  can  send  a  window  function  more  than  100  different  messages.  The 
WINDOWS.H  header  file  includes  identifiers  for  all  these  messages  so  that  C  programmers 
do  not  have  to  remember  the  message  numbers.  Some  of  the  more  common  messages  and 
the  meanings  of  the  wParam  and  iParam  parameters  are  discussed  here: 

WM^CREATE.  Windows  sends  a  window  function  this  nonqueued  message  while  pro¬ 
cessing  the  CreateWindow  call.  The  IParam  parameter  is  a  pointer  to  a  creation  structure. 
A  window  function  can  perform  some  program  initialization  during  the  WM_CREATE 
message, 

WM_MOVE.  Windows  sends  a  window  function  the  nonqueued  WM_MOVE  message 
when  the  window  has  been  moved  to  another  part  of  the  display.  The  IParam  parameter 
gives  the  new  coordinates  of  the  window  relative  to  the  upper  left  corner  of  the  screen. 

WM^SIZE.  This  nonqueued  message  indicates  that  the  size  of  the  window  has  been 
changed.  The  new  size  is  encoded  in  the  IParam  parameter.  Programs  often  save  this 
window  size  for  later  use. 

WM_  PAINT.  This  queued  message  indicates  that  a  region  in  the  window’s  client  area 
needs  repainting.  (The  message  queue  can  contain  only  one  WM_  PAINT  message.) 

WM_COMMAND.  This  nonqueued  message  signals  a  program  that  a  user  has  selected  a 
menu  item  or  has  triggered  a  keyboard  accelerator.  Child-window  controls  also  use 
WM__COMMAND  to  send  messages  to  the  parent  window. 

WM^KEYDOWN.  The  wParam  parameter  of  this  queued  message  is  a  virtual  key  code 
that  identifies  the  key  being  pressed.  The  IParam  parameter  includes  flags  that  indicate 
the  previous  key  state  and  the  number  of  keypresses  the  message  represents. 

WM^KEYUP.  This  queued  message  tells  a  window  function  that  a  key  has  been  released. 
The  wParam  parameter  is  a  virtual  key  code. 

WM^CHAR.  This  queued  message  is  generated  from  WM_KEYDOWN  messages  during 
the  TranslateMessage  call.  The  wParam  parameter  is  the  ASCII  code  of  a  keyboard  key. 

WM_MOUSEMOVE.  Windows  uses  this  queued  message  to  tell  a  program  about  mouse 
movement.  The  IParam  parameter  contains  the  coordinates  of  the  mouse  relative  to  the 
upper  left  corner  of  the  client  area  of  the  window.  The  wParam  parameter  contains  flags 
that  indicate  whether  any  mouse  buttons  or  the  Shift  or  Ctrl  keys  are  currently  pressed. 

WM_idBUTTONDOWN.  This  queued  message  tells  a  program  that  a  button  on  the  mouse 
was  depressed  while  the  mouse  was  in  the  window’s  client  area.  The  xc3.n  be  either  L,  R, 
or  M  for  the  left,  right,  or  middle  mouse  button.  The  wParam  and  IParam  parameters  are 
the  same  as  for  WM^MOUSEMOVE. 
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WM^xBUTTONUP.  This  queued  message  tells  a  program  that  the  user  has  released  a 
mouse  button. 

WM^xBUTTONDBLCLK.  When  the  user  double-clicks  a  mouse  button,  Windows 
generates  a  WM_xBUTTONDOWN  message  for  the  first  click  and  a  queued 
WM__  JcBUTTONDBLCLK  message  for  the  second  click. 

WMjtiMER.  When  a  Windows  program  sets  a  timer  with  the  SetTimer  function, 
Windows  places  a  WM_TIMER  message  in  the  message  queue  at  periodic  intervals. 

The  wParam  parameter  is  a  timer  ID.  (If  the  message  queue  already  contains  a 
WM_TIMER  message,  Windows  does  not  add  another  one  to  the  queue.) 

WM_ySCROLL  A  Windows  program  that  includes  a  vertical  scroll  bar  in  its  window 
receives  nonqueued  WM_ySCROLL  messages  indicating  various  types  of  scroll-bar 
manipulation. 

WM^HSCROLL  This  nonqueued  message  indicates  a  user  is  manipulating  a  horizontal 
scroll  bar. 

WM_CLOSE.  Windows  sends  a  window  function  this  nonqueued  message  when  the  user 
has  selected  Close  horn  the  window’s  system  menu.  A  program  can  query  the  user  to  de¬ 
termine  whether  any  action,  such  as  saving  a  file  to  disk,  is  needed  before  the  program 
is  terminated. 

WM^QUERYENDSESSIOK  This  nonqueued  message  indicates  that  the  user  is  shutting 
down  Windows  by  selecting  Close  from  the  MS-DOS  Executive  system  menu.  A  program 
can  request  the  user  to  verify  that  the  program  should  be  ended.  If  the  window  function 
returns  a  zero  value  from  the  message,  Windows  does  not  end  the  session. 

WM^  DESTROY.  This  nonqueued  message  is  the  last  message  a  window  function  receives 
before  the  program  ends.  A  window  function  can  perform  some  last-minute  cleanup  while 
processing  WM_  DESTROY. 

WM^QUIT.  This  is  a  queued  message  that  never  reaches  the  window  function  because  it 
causes  GetMessage  to  return  a  zero  value  that  causes  the  program  to  exit  the  message  loop. 

Message  processing 

Programmers  can  choose  to  process  some  messages  and  ignore  others  in  the  window 
function.  Messages  that  are  ignored  are  generally  passed  on  to  the  function 
Def  WindowProc  for  default  processing  within  Windows. 

Because  Windows  eventually  has  access  to  messages  that  a  window  function  does  not 
process,  it  can  send  a  program  messages  that  might  otherwise  be  regarded  as  pertaining  to 
system  functions — for  example,  mouse  messages  that  occur  in  a  nonclient  area  of  the  win¬ 
dow,  or  system  keyboard  messages  that  affect  the  menu.  Unless  these  messages  are  passed 
on  to  Def  WindowProc,  the  menu  and  other  system  functions  do  not  work  properly. 

A  program  can,  however,  trap  some  of  these  messages  to  override  Windows’  default  pro¬ 
cessing.  For  example,  when  Windows  needs  to  repaint  the  nonclient  area  of  a  window  (the 
title  bar,  system-menu  box,  and  scroll  bars),  it  sends  the  window  function  a  WMLNCPAINT 
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(nonclient  paint)  message.  The  window  function  normally  passes  this  message  to 
Def  WindowProc,  which  then  calls  routines  to  update  the  nonclient  areas  of  the  window. 
The  program  can,  however,  choose  to  process  the  WM_NCPAINT  message  and  paint  the 
nonclient  area  itself.  A  program  that  does  this  can,  for  example,  draw  its  own  scroll  bars. 

The  Windows  messaging  system  also  notifies  a  program  of  important  events  occurring 
outside  its  window.  For  example,  if  the  MS-DOS  Executive  were  simply  to  end  the  Win¬ 
dows  session  when  the  user  selects  the  Close  option  from  its  system  menu,  then  applica¬ 
tions  that  were  still  running  would  not  have  a  chance  to  save  changed  files  to  disk.  Instead, 
when  the  user  selects  Close  from  the  last  instance  of  the  MS-DOS  Executive’s  system 
menu,  the  MS-DOS  Executive  sends  a  WM__QUERYENDSESSION  message  to  each  cur¬ 
rently  running  application.  If  any  application  responds  by  returning  a  zero  value,  the  MS- 
DOS  Executive  does  not  end  the  Windows  session. 

Before  responding,  an  application  can  process  the  WM_QUERYENDSESSION  message 
and  display  a  message  box  asking  the  user  if  a  file  should  be  saved.  The  message  box 
should  include  three  buttons  labeled  Yes,  No,  and  Cancel.  If  the  user  answers  Yes,  the  pro¬ 
gram  can  save  the  file  and  then  return  a  nonzero  value  to  the  WM_QUERYENDSESSION 
message.  If  the  user  answers  No,  the  program  can  return  a  nonzero  value  without  saving 
the  file.  But  if  the  user  answers  Cancel,  the  program  should  return  a  zero  value  so  that 
the  Windows  session  will  not  be  ended.  If  a  program  does  not  process  the 
WM^QUERYENDSESSION  message,  Def  WindowProc  returns  a  nonzero  value. 

When  a  user  selects  Close  from  the  system  menu  of  a  particular  instance  of  an  application, 
rather  than  from  the  MS-DOS  Executive’s  menu,  Windows  sends  the  window  function  a 
WM_CLOSE  message.  If  the  program  has  an  unsaved  file  loaded,  it  can  query  the  user  with 
a  message  box — possibly  the  same  one  displayed  when  WM_QUERYENDSESSION  is 
processed.  If  the  user  responds  Yes  to  the  query,  the  program  can  save  the  file  and  then 
call  DestroyWindow,  If  the  user  responds  No,  the  program  can  call  DestroyWindow 
without  saving  the  file.  If  the  user  responds  Cancel,  the  window  function  does  not  call 
DestroyWindow  and  the  program  will  not  be  terminated.  If  a  program  does  not  process 
WM_CLOSE  messages,  Def  WindowProc  calls  DestroyWindow. 

Finally,  a  window  function  can  send  messages  to  other  window  functions,  either  within 
the  same  program  or  in  other  programs,  with  the  Windows  SendMessage  function.  This 
function  returns  control  to  the  calling  program  after  the  message  has  been  processed.  A 
program  can  also  place  messages  in  a  program’s  message  queue  with  the  PostMessage 
function.  This  function  returns  control  immediately  after  posting  the  message. 

For  example,  when  a  program  makes  changes  to  the  WIN.INI  file  (a  file  containing 
Windows  initialization  information),  it  can  notify  all  currently  running  instances  of  these 
changes  by  sending  them  a  WM_WININICHANGE  message: 

SendMessage  (-1,  WM_WININICHANGE,  0,  OL)  ; 

The  -1  parameter  indicates  that  the  message  is  to  be  sent  to  all  window  functions  of 
all  currently  running  instances.  Windows  calls  the  window  functions  with  the 
WM__WININICHANGE  message  and  then  returns  control  to  the  program  that  sent  the 
message. 
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SAMPLE’S  message  processing 

The  SAMPLE  program  shown  in  Figure  17-11  processes  only  four  messages: 
WM_COMMAND,  WM_SIZE,  PAINT,  and  WM_  DESTROY.  All  other  messages  are 

passed  to  Def  WindowProc.  As  is  typical  with  most  Windows  programs  written  in  C, 
SAMPLE  uses  a  switch  and  case  construction  for  processing  messages. 

The  WM_COMMAND  message  signals  the  program  that  the  user  has  selected  a  new  font 
from  the  menu.  SAMPLE  first  obtains  a  handle  to  the  menu  and  removes  the  checkmark 
from  the  previously  selected  font: 

hMenu  =  GetMenu  (hWnd)  ; 

CheckMenuItem  (hMenu,  nCurrentFont,  MF_UNCHECKED)  ; 

The  value  of  wParam  in  the  WM^COMMAND  message  is  the  menu  ID  of  the  newly 
selected  font.  SAMPLE  saves  that  value  in  a  static  variable  (nCurrentFont)  and  then  places  a 
checkmark  on  the  new  menu  choice: 

nCurrentFont  =  wParam  ; 

CheckMenuItem  (hMenu,  nCurrentFont,  MF_CHECKED)  ; 

Because  the  typeface  has  changed,  SAMPLE  must  repaint  its  display.  The  program  does 
not  repaint  it  immediately,  however.  Instead,  it  calls  the  InvalidateRect  function: 

InvalidateRect  (hWnd,  NULL,  TRUE)  / 

This  causes  a  WM_PAINT  message  to  be  placed  in  the  program’s  message  queue.  The 
NULL  parameter  indicates  that  the  entire  client  area  should  be  repainted.  The  TRUE 
parameter  indicates  that  the  background  should  be  erased. 

The  WM_SI2E  message  indicates  that  the  size  of  SAMPLE’S  client  area  has  changed. 
SAMPLE  simply  saves  the  new  dimensions  of  the  client  area  in  two  static  variables: 

xClient  =  LOWORD  (IParam)  ; 
yClient  =  HIWORD  (IParam)  ; 

The  LOWORD  and  HIWORD  macros  are  defined  in  WINDOWS.H. 

Windows  also  places  a  WM_  PAINT  message  in  SAMPLE’S  message  queue  when  the  size 
of  the  client  area  has  changed.  As  is  the  case  with  WM_COMMAND,  the  program  does 
not  have  to  repaint  the  client  area  immediately,  because  the  WM_  PAINT  message  is  in  the 
message  queue. 

SAMPLE  can  receive  a  WM>_  PAINT  message  for  many  reasons.  The  first  WM__  PAINT  mes¬ 
sage  it  receives  results  from  calling  UpdateWindow  in  the  WinMain  function.  Later,  if  the 
current  font  is  changed  from  the  menu,  the  program  itself  causes  a  WM_  PAINT  message 
to  be  placed  in  the  message  queue  by  calling  InvalidateRect.  Windows  also  sends  a  win¬ 
dow  function  a  WM_  PAINT  message  whenever  the  user  changes  the  size  of  the  window 
or  when  part  of  the  window  previously  covered  by  another  window  is  uncovered. 

Programs  begin  processing  WM_  PAINT  messages  by  calling  Begin  Paint: 


BeginPaint  (hWnd,  &ps)  ; 
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The  SAMPLE  program  then  creates  a  font  based  on  the  current  size  of  the  client  area  and 
the  current  typeface  selected  from  the  menu: 

hFont  =  CreateFont  (yClient,  xClient  /  8, 

0,  0,  400,  0,  0,  0,  OEM_CHARSET, 

OUT_STROKE_PRECIS,  OUT_STROKE_PRECIS, 

DRAFT_QUALITY,  (BYTE)  VARIABLE-PITCH  1 
cFamily  [nCurrentFont  -  IDM_SCRIPT] , 
szFace  [nCurrentFont  -  IDM_SCRIPT] )  ; 

The  font  is  selected  into  the  device  context  (a  data  structure  internal  to  Windows  that 
describes  the  characteristics  of  the  output  device);  the  program  also  saves  the  original 
device-context  font: 

hFont  =  SelectObject  (ps.hdc,  hFont)  ; 

And  the  word  Windows  is  displayed: 

TextOut  (ps.hdc,  0,  0,  "Windows”,  7)  ; 

The  original  font  in  the  device  context  is  then  selected,  and  the  font  that  was  created  is 
now  deleted: 

DeleteObject  (SelectObject  (ps.hdc,  hFont))  ; 

Finally,  SAMPLE  calls  EndPaint  to  signal  Windows  that  the  client  area  is  now  updated  and 
valid: 

EndPaint  (hWnd,  &ps)  ; 

Although  the  processing  of  the  WM_  PAINT  message  in  this  program  is  simple,  the 
method  used  is  common  to  all  Windows  programs.  The  Begin  Paint  and  EndPaint  func¬ 
tions  always  occur  in  pairs,  first  to  get  information  about  the  area  that  needs  repainting 
and  then  to  mark  that  area  as  valid. 

SAMPLE  will  display  this  text  even  when  the  program  is  minimized  to  be  displayed  as  an 
icon  at  the  bottom  of  the  screen.  Although  most  Windows  programs  use  a  customized  icon 
for  this  purpose,  the  window-class  structure  in  SAMPLE  indicates  that  the  program’s  icon 
is  NULL,  meaning  that  the  program  is  responsible  for  drawing  its  own  icon.  SAMPLE  does 
not,  however,  make  any  special  provisions  for  drawing  the  icon.  To  it,  the  icon  is  simply 
a  small  client  area.  As  a  result,  SAMPLE  displays  the  word  Windows  in  its  “icon,”  using  a 
small  font  size. 

Windows  sends  the  window  function  the  WM_DESTROY  message  as  a  result  of  the 
DestroyWindow  function  that  Def  WindowProc  calls  when  processing  a  WM_ CLOSE 
message.  The  standard  processing  involves  placing  a  WM-.QUIT  message  in  the  message 
queue: 

PostQuitMessage  (0)  ; 

When  the  GetMessage  function  retrieves  WM_QUIT  from  the  message  queue,  GetMessage 
returns  0.  This  terminates  the  message  loop  and  the  program. 
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For  all  other  messages,  SAMPLE  calls  Def  WindowProc  and  exits  the  window  function  by 
returning  the  value  from  the  call: 

return  Def Window? roc  (hWnd,  iMessage,  wParam,  iParam)  ; 

This  allows  Windows  to  perform  default  processing  on  the  messages  SAMPLE  ignores. 

Windows’  multitasking 

Most  operating  systems  or  operating  environments  that  allow  multitasking  use  what  is 
called  a  preemptive  scheduler.  Generally,  the  procedure  involves  use  of  the  computer’s 
clock  to  switch  rapidly  between  programs  and  allow  each  a  small  time  slice.  When 
switching  between  programs,  the  operating  system  must  preserve  the  machine  state. 

Windows  is  different.  It  is  a  nonpreemptive  multitasking  environment.  Although  Windows 
allows  several  programs  to  run  simultaneously,  it  never  switches  from  one  program  to 
allow  another  to  run.  It  switches  between  programs  only  when  the  currently  running  pro¬ 
gram  calls  the  GetMessage  function  or  the  related  PeekMessage  and  WaitMessage 
functions. 

When  a  Windows  program  calls  GetMessage  and  the  program’s  message  queue  contains 
a  message  other  than  WM_  PAINT  or  WM^TIMER,  Windows  return's  control  to  the  pro¬ 
gram  with  the  next  message.  However,  if  the  program’s  message  queue  contains  only  a 
WM_PAINT  or  WM_TIMER  message  and  another  program’s  queue  contains  a  message 
other  than  WM_  PAINT  or  WM_TIMER,  Windows  returns  control  to  the  other  program, 
which  is  also  waiting  for  its  GetMessage  call  to  return. 

(Windows  also  switches  between  programs  temporarily  when  a  program  uses 
SendMessage  to  send  a  message  to  a  window  function  in  another  program,  but  control 
returns  to  the  calling  program  after  the  window  function  has  processed  the  message  sent 
to  it.) 

To  cooperate  with  Windows’  nonpreemptive  multitasking,  programmers  should  try  to 
perform  message  processing  as  quickly  as  possible.  Programs  can,  for  example,  split  a 
large  amount  of  processing  into  several  smaller  pieces  to  allow  other  programs  to  run  in 
the  interval.  During  long  processing  a  program  can  also  periodically  call  PeekMessage  to 
allow  other  programs  to  run. 


Graphics  Device  Interface 

Programs  receive  input  through  the  Windows  message  system.  For  program  output, 
Windows  provides  a  device-independent  interface  to  graphics  output  devices,  such  as  the 
video  display,  printers,  and  plotters.  This  interface  is  called  the  Graphics  Device  Interface, 
or  GDI. 
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The  device  context  (DC) 

When  a  Windows  program  needs  to  send  output  to  the  video  screen,  the  printer,  or 
another  graphics  output  device,  it  must  first  obtain  a  handle  to  the  device’s  device  context, 
or  DC.  Windows  provides  a  number  of  functions  for  obtaining  this  device-context  handle: 

Begin  Paint  Used  for  obtaining  a  video  device-context  handle  during  processing  of  a 
WM_PAINT  message.  This  device  context  applies  only  to  the  rectangular  section  of  the 
client  area  that  is  invalid  (needs  repainting).  This  region  is  also  a  clipping  region,  meaning 
that  a  program  cannot  paint  outside  this  rectangle.  BeginPaint  fills  in  the  fields  of  a 
PAINTSTRUCT  structure.  This  structure  contains  the  coordinates  of  the  invalid  rectangle 
and  a  byte  that  indicates  if  the  background  of  the  invalid  rectangle  has  been  erased. 

GetDC.  Generally  used  for  obtaining  a  video  device-context  handle  during  processing  of 
messages  other  than  WM_  PAINT.  The  handle  obtained  with  this  function  references  only 
the  client  area  of  the  window. 

GetWindowDC.  Used  for  obtaining  a  video  device-context  handle  that  encompasses  the 
entire  window,  including  the  title  bar,  menu  bar,  and  scroll  bars.  A  Windows  program  can 
use  this  function  if  it  is  necessary  to  paint  over  areas  of  the  window  outside  the  client  area. 

CreateDC.  Used  for  obtaining  a  device-context  handle  for  the  entire  display  or  for  a 
printer,  a  plotter,  or  other  graphics  output  device. 

CreateIC,  Used  for  obtaining  an  information-context  handle,  which  is  similar  to  a 
device-context  handle  but  can  be  used  only  for  obtaining  information  about  the  output 
device,  not  for  drawing. 

CreateCompatibleDC.  Used  for  obtaining  a  device-context  handle  to  a  memory  device 
context  compatible  with  a  particular  graphics  output  device.  This  function  is  generally 
used  for  transferring  bitmaps  to  a  graphics  output  device. 

CreateMetaFile.  Used  for  obtaining  a  metafile  device-context  handle.  A  metafile  is  a  collec¬ 
tion  of  GDI  calls  encoded  in  binary  form. 

The  Windows  program  uses  the  device-context  handle  when  calling  GDI  functions.  In 
addition  to  drawing,  the  various  GDI  functions  can  change  the  attributes  of  the  device  con¬ 
text,  select  different  drawing  objects  (such  as  pens  and  fonts)  into  the  device  context,  and 
determine  the  characteristics  of  the  device  context. 

Device-independent  programming 

Windows  supports  such  a  wide  variety  of  video  displays,  printers,  and  plotters  that  pro¬ 
grams  cannot  make  assumptions  about  the  size  and  resolution  of  the  device.  Furthermore, 
because  the  user  can  generally  alter  the  size  of  a  program’s  window,  the  program  must  be 
able  to  adjust  its  output  appropriately.  The  SAMPLE  program,  for  example,  showed  how 
the  window  function  can  use  the  WM_SIZE  message  to  obtain  the  current  size  of  a  win¬ 
dow  to  create  a  font  that  fits  text  within  the  window’s  client  area. 

Programs  can  also  use  other  Windows  functions  to  determine  the  physical  characteristics 
of  a  device.  For  instance,  a  program  can  use  the  GetDeviceCaps  function  to  obtain 
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information  about  the  device  context,  including  the  resolution  of  the  device,  its  physical 
dimensions,  and  its  relative  pixel  height  and  width. 

Then,  too,  the  GetTextMetrics  function  returns  information  about  the  current  font  selected 
in  the  device  context.  In  the  default  device  context,  this  is  the  system  font.  Many  Windows 
programs  base  the  size  of  their  display  output  on  the  size  of  a  system-font  character. 

Device-context  attributes 

The  device  context  includes  attributes  that  define  how  the  graphics  output  functions  work 
on  the  device.  When  a  program  first  obtains  a  handle  to  a  device  context,  Windows  sets 
these  attributes  to  default  values,  but  the  program  can  change  them.  Some  of  these 
device-context  attributes  are  as  follows: 

Pen.  Windows  uses  the  current  pen  for  drawing  lines.  The  default  pen  produces  a  solid 
black  line  1  pixel  wide.  A  program  can  change  the  pen  color,  change  to  a  dotted  or  dashed 
line,  or  make  the  pen  draw  a  solid  line  wider  than  1  pixel. 

Brush.  Windows  uses  the  current  brush  (sometimes  called  a  pattern)  for  filling  areas.  A 
brush  is  an  8-pixel-by-8-pixel  bitmap.  The  default  brush  is  solid  white.  Programs  can 
create  colored  brushes,  hatched  brushes,  and  customized  brushes  based  on  bitmaps. 

Background  color.  Windows  uses  the  background  color  to  fill  the  spaces  in  and  between 
characters  when  drawing  text  and  to  color  the  open  areas  in  hatched  brushstrokes  and 
dotted  or  dashed  pen  lines.  Windows  uses  the  background  color  only  if  the  background 
mode  (another  attribute  of  the  display  context)  is  opaque.  If  the  background  mode  is 
transparent,  Windows  leaves  the  background  unaltered.  The  default  background  color 
is  white. 

Text  color.  Windows  uses  this  color  for  drawing  text.  The  default  is  black. 

Font.  Windows  uses  the  font  to  determine  the  shape  of  text  characters.  The  default  is 
called  the  system  font,  a  fixed-pitch  font  that  also  appears  in  menus,  caption  bars,  and 
dialog  boxes. 

Additional  device-context  attributes  (such  as  mapping  modes)  are  described  in  the  follow¬ 
ing  sections. 

Mapping  modes 

Most  GDI  drawing  functions  in  Windows  have  parameters  that  specify  the  coordinates  or 
size  of  an  object.  For  instance,  the  Rectangle  function  has  five  parameters: 

Rectangle  (hDC,  x1 ,  yl ,  x2,  y2)  ; 

The  first  parameter  is  the  handle  to  the  device  context.  The  others  are 

•  xT.  horizontal  coordinate  of  the  upper  left  corner  of  the  rectangle. 

•  yT.  vertical  coordinate  of  the  upper  left  corner  of  the  rectangle. 

•  x2\  horizontal  coordinate  of  the  lower  right  corner  of  the  rectangle. 

•  y2\  vertical  coordinate  of  the  lower  right  corner  of  the  rectangle. 
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In  the  Rectangle  and  most  other  GDI  functions,  coordinates  are  logical  coordinates,  which 
are  not  necessarily  the  same  as  the  physical  coordinates  (pixels)  of  the  device.  To  translate 
logical  coordinates  into  physical  coordinates,  Windows  uses  the  current  mapping  mode. 

In  actuality,  the  mapping  mode  defines  a  transformation  of  coordinates  between  a  win¬ 
dow,  which  is  defined  in  terms  of  logical  coordinates,  and  a  viewport,  which  is  defined  in 
terms  of  physical  coordinates.  For  any  mapping  mode,  a  program  can  define  separate  win¬ 
dow  and  viewport  origins.  The  logical  point  defined  as  the  window  origin  is  then  mapped 
to  the  physical  point  defined  as  the  viewport  origin.  For  some  mapping  modes,  a  program 
can  also  define  window  and  viewport  extents,  which  determine  how  the  logical  coordi¬ 
nates  are  scaled  to  the  physical  coordinates. 

Windows  programs  can  select  one  of  eight  mapping  modes.  The  first  six  are  sometimes 
called  fully  constrained,  because  the  ratio  between  the  window  and  viewport  extents  is 
fixed  and  cannot  be  changed. 

In  MM_TEXT,  the  default  mapping  mode,  coordinates  on  the  x  axis  increase  from  left  to 
right,  and  coordinates  on  the  y  axis  increase  from  the  top  downward.  In  the  other  five  fully 
constrained  mapping  modes,  coordinates  on  the  x  axis  also  increase  from  left  to  right,  but 
coordinates  on  the  y  axis  increase  from  the  bottom  upward.  The  six  fully  constrained 
mapping  modes  are 

•  MM^TEXT:  Logical  coordinates  are  the  same  as  physical  coordinates. 

•  MM^OMETRIO.  Logical  coordinates  are  in  units  of  0.1  millimeter. 

•  MM_HIMETRIC:  Logical  coordinates  are  in  units  of  0.01  millimeter. 

•  MM^OENGLISH:  Logical  coordinates  are  in  units  of  0.01  inch. 

•  MMJtilENGLISH:  Logical  coordinates  are  in  units  of  0.001  inch. 

•  MM^TWIPS:  Logical  coordinates  are  in  units  of  Vuao  inch.  (These  units  are  V20  of  a 
typographic  point,  which  is  approximately  Viz  inch.) 

The  seventh  mapping  mode  is  called  partially  constrained,  because  a  program  can  change 
the  window  and  viewport  extents  but  Windows  adjusts  the  values  to  ensure  that  equal 
horizontal  and  vertical  logical  coordinates  translate  to  equal  horizontal  and  vertical  physical 
dimensions: 

•  MMUISOTROPIO,  Logical  coordinates  represent  the  same  physical  distance  on  both 
the  X  and  y  axes. 

The  MM_ISOTROPIC  mapping  mode  is  useful  for  drawing  circles  and  squares.  The 
MM_LOMETRIC,  MM^HIMETRIC,  MM^LOENGLISH,  MM^HIENGLISH,  and 
MM_TWIPS  mapping  modes  are  also  isotropic,  because  equal  logical  coordinates  map  to 
the  same  physical  dimensions  on  both  axes. 

The  final  mapping  mode  is  sometimes  called  unconstrained  because  a  program  is  free  to 
set  different  window  and  viewport  extents  on  the  x  and  y  axes. 

•  MM^ANISOTROPIC:  Logical  coordinates  are  mapped  to  arbitrarily  scaled  physical 
coordinates. 
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Functions  for  drawing 

Windows  includes  several  functions  that  programs  can  use  to  draw  in  the  client  area  of  a 
window.  The  most  common  of  these  functions  are 

SetPixel.  Sets  a  point  to  a  particular  color. 

LineTo.  Draws  a  line  from  the  current  position  to  a  point  specified  in  the  LineTo  function. 
The  current  position  is  defined  in  the  device  context  and  can  be  altered  before  the  call  to 
LineTo  with  the  MoveTo  function,  which  changes  the  current  position  but  does  not  draw 
anything.  Windows  uses  the  current  pen  and  the  current  drawing  mode  isee  below)  for 
drawing  the  line. 

Polyline.  Draws  multiple  lines  much  like  a  series  of  LineTo  calls  but  does  not  alter  the  cur¬ 
rent  position  on  completion. 

Rectangle.  Draws  a  filled  rectangle  with  a  border.  Parameters  to  the  Rectangle  function 
specify  the  coordinates  of  the  upper  left  and  lower  right  corners  of  the  rectangle.  Windows 
draws  the  border  of  the  rectangle  with  the  current  pen  and  current  drawing  mode  defined 
in  the  device  context,  just  as  if  it  were  using  the  Polyline  function  then  Windows  fills  the 
rectangle  with  the  current  brush  defined  in  the  device  context. 

Ellipse.  Uses  the  same  parameters  as  Rectangle  but  draws  an  ellipse  within  the  rectangular 
area. 

RoundRect.  Draws  a  rectangle  with  rounded  corners.  Two  parameters  to  this  function 
define  the  height  and  width  of  an  ellipse  that  Windows  uses  for  drawing  the  rounded 
corners. 

Polygon.  Draws  a  polygon  connecting  a  series  of  points  and  fills  the  enclosed  areas  in 
either  an  alternate  or  winding  mode.  The  winding  mode  causes  Windows  to  fill  every  area 
within  the  polygon.  The  alternate  mode  fills  every  other  area.  For  a  polygon  that  defines  a 
five-pointed  star,  for  instance,  the  center  is  filled  if  the  mode  is  winding  but  is  not  filled  if 
the  mode  is  alternate. 

Arc.  Draws  a  curved  line  that  is  part  of  the  circumference  of  an  ellipse. 

Chord.  Similar  to  the  Arc  function,  but  Windows  connects  the  beginning  and  ending 
points  of  the  arc  with  a  straight  line.  The  area  is  filled  with  the  current  brush  defined  in 
the  device  context. 

Pie.  Similar  to  the  Arc  function,  but  Windows  draws  lines  from  the  beginning  and  ending 
points  of  the  arc  to  the  center  of  the  ellipse.  The  area  is  filled  with  the  current  brush 
defined  in  the  device  context. 

TextOut.  Writes  text  with  the  current  font,  text  color,  background  color,  and  background 
mode  (transparent  or  opaque). 

Windows  also  includes  other  drawing  functions  for  filling  areas,  formatting  text,  and  trans¬ 
ferring  bitmaps. 
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Raster  operations  for  pens 

When  Windows  uses  a  pen  to  write  to  a  device  context,  it  must  first  determine  which  pix¬ 
els  of  the  destination  are  to  be  altered  by  the  pen  (the  foreground)  and  which  pixels  will 
not  be  affected  (the  background).  With  dotted  and  dashed  pens,  the  background — 
the  space  between  the  dots  or  dashes — is  left  unaltered  if  the  drawing  mode  is  trans¬ 
parent  and  is  filled  with  the  background  color  if  the  drawing  mode  is  opaque. 

When  Windows  alters  the  pixels  of  the  destination  that  correspond  to  the  foreground  of 
the  pen,  the  most  obvious  result  is  that  the  color  of  the  current  pen  defined  in  the  display 
context  is  used  to  color  the  destination.  But  this  is  not  the  only  possible  result.  Windows 
also  generalizes  the  process  by  using  a  logical  operation  to  combine  the  pixels  of  the  pen 
and  the  pixels  of  the  destination. 

This  logical  operation  is  defined  by  the  drawing  mode  attribute  of  the  device  context.  This 
drawing  mode  can  be  set  to  one  of  16  binary  raster  operations  (abbreviated  ROP2). 

The  following  table  shows  the  16  binary  raster  operation  codes  defined  in  WINDOWS.H. 
The  column  headed  “Resultant  Destination”  shows  how  the  destination  changes,  depend¬ 
ing  on  the  bit  pattern  of  the  pen  and  the  bit  pattern  of  the  destination  before  the  line  is 
drawn.  The  words  OR,  AND,  XOR,  and  NOT  are  the  logical  operations. 


Binary  Raster  Resultant 

Operation  Destination 


R2_BLACK 

R2_COPYPEN 

R2_MERGEPEN 

R2_MASKPEN 

R2_XORPEN 

R2_NOTCOPYPEN 

R2_NOTMERGEPEN 

R2_NOTMASKPEN 

R2_NOTXORPEN 

R2_MERGEPENNOT 

R2_MASKPENNOT 

R2_MERGENOTPEN 

R2_MASKNOTPEN 

R2_NOP 

R2_NOT 

R2_WHITE 


0 

pen 

pen  OR  destination 
pen  AND  destination 
pen  XOR  destination 
NOT  pen 

NOT  (pen  OR  destination) 
NOT  (pen  AND  destination) 
NOT  (pen  XOR  destination) 
pen  OR  (NOT  destination) 
pen  AND  (NOT  destination) 
(NOT  pen)  OR  destination 
(NOT  pen)  AND  destination 
destination 
NOT  destination 
1 


The  default  drawing  mode  defined  in  a  device  context  is  R2_COPYPEN,  which  simply 
copies  the  pen  to  the  destination.  However,  if  the  pen  color  is  blue,  the  destination  is  red, 
and  the  drawing  mode  is  R2_MERGEPEN,  then  the  drawn  line  appears  as  magenta,  which 
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results  from  combining  the  pen  and  destination  colors.  If  the  pen  color  is  blue,  the  desti¬ 
nation  is  red,  and  the  drawing  mode  is  R2_NOTMERGEPEN,  then  the  drawn  line  is  green, 
because  the  blue  pen  and  the  red  destination  are  combined  into  magenta,  which  Windows 
then  inverts  to  make  green. 

Bit-block  transfers 

Windows  also  uses  logical  operations  when  transferring  a  rectangular  pixel  pattern  (a  bit 
block)  from  one  device  context  to  another  or  from  one  area  of  a  device  context  to  another 
area  of  the  same  device  context. 

While  line  drawing  involves  a  logical  combination  of  two  sets  of  pixels  (the  pen  and  the 
destination),  the  bit-block  transfer  functions  perform  a  logical  combination  of  three  sets 
of  pixels:  a  source  bitmap,  a  destination  bitmap,  and  the  brush  currently  selected  in  the 
destination  device  context.  As  shown  in  the  preceding  section,  there  are  16  different  ROP2 
drawing  modes  for  all  the  possible  combinations  of  two  sets  of  pixels.  The  tertiary  raster 
operations  (abbreviated  ROP3)  for  bit-block  transfers  require  256  different  operations  for 
all  possible  combinations. 

Windows  defines  three  functions  for  transferring  rectangular  pixel  patterns:  BitBlt  (bit- 
block  transfer),  StretchBlt  (stretch-block  transfer),  and  PatBlt  (pattern-block  transfer).  Of 
these  three  functions,  StretchBlt  is  the  most  generalized.  StretchBlt  transfers  a  bitmap  from 
a  source  device  context  to  a  destination  device  context.  Function  parameters  specify  the 
origin,  width,  and  height  of  the  bitmap.  If  the  source  and  destination  widths  and  heights 
are  different,  Windows  stretches  or  compresses  the  bitmap  appropriately.  Negative  values 
of  widths  and  heights  cause  Windows  to  draw  a  mirror  image  of  the  bitmap. 

The  BitBlt  function  transfers  a  bitmap  from  a  source  device  context  to  a  destination  device 
context,  but  the  width  and  height  of  the  source  and  destination  must  be  the  same.  If  the 
source  and  destination  device  contexts  have  different  mapping  modes,  Windows  uses 
StretchBlt  instead. 

In  both  BitBlt  and  StretchBlt,  Windows  performs  a  bit-by-bit  logical  operation  with  the  bit 
block  in  the  source  device  context,  the  bit  block  in  the  destination  area  of  the  destination 
device  context,  and  the  brush  currently  selected  in  the  destination  device  context. 
Although  Windows  supports  all  256  possible  raster  operations  with  these  three  bitmaps, 
only  a  few  have  been  given  WINDOWS.H  identifiers: 


Raster  Resultant 

Operation  Destination 


BLACKNESS 

SRCCOPY 

SRCAND 

SRCPAINT 


0 

source 

source  AND  destination 
source  OR  destination 


(more) 
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Raster  Resultant 

Operation  Destination 


SRCINVERT 

SRCERASE 

MERGEPAINT 

NOTSRCCOPY 

NOTSRCERASE 

DSTINVERT 

PATCOPY 

MERGECOPY 

PATINVERT 

PATPAINT 

WHITENESS 


source  XOR  destination 
source  AND  (NOT  destination) 
source  OR  (NOT  destination) 

NOT  source 

NOT  (source  OR  destination) 

NOT  destination 
pattern 

source  AND  pattern 
destination  XOR  pattern 
source  OR  (NOT  destination)  OR  pattern 
1 


The  PatBlt  function  is  similar  to  BitBlt  and  StretchBlt  but  performs  a  logical  operation  only 
between  the  currently  selected  brush  and  a  destination  area  of  the  device  context.  Thus, 
only  16  raster  operations  can  be  used  with  PatBlt;  these  are  equivalent  to  the  binary  raster 
operations  used  with  line  drawing. 

Text  and  fonts 

Windows  supports  file-based  text  fonts  in  two  different  formats:  raster  and  vector.  The 
raster  fonts,  such  as  Courier,  Helvetica,  and  Times  Roman,  are  defined  by  digital  represen¬ 
tations  of  the  bit  patterns  of  the  characters.  Font  files  usually  contain  several  different  sizes 
for  each  typeface.  The  vector  fonts,  such  as  Modern,  Script,  and  Roman,  are  defined  by 
points  that  are  connected  to  form  the  letters  and  can  be  scaled  to  different  sizes. 

When  using  a  device  such  as  a  printer,  which  has  built-in  fonts,  Windows  can  also  use 
these  device-based  fonts. 

To  specify  a  font,  a  Windows  program  uses  the  CreateFont  function  to  create  a  logical 
font — a  detailed  description  of  the  desired  font.  When  this  logical  font  is  selected  into  a 
device  context,  Windows  finds  the  actual  font  that  best  fits  this  description.  In  many  cases, 
this  match  is  not  exact.  The  program  can  then  call  GetTextMetrics  to  determine  the  char¬ 
acteristics  of  the  actual  font  that  the  device  will  use  to  display  text. 

Windows  supports  both  fixed-width  and  variable-width  fonts,  as  well  as  such  attributes  as 
italics,  underlining,  and  boldfacing.  Programs  can  also  justify  text  with  the  GetTextExtent 
call,  which  obtains  the  width  of  a  particular  text  string.  The  program  can  then  insert  extra 
spaces  between  words  with  SetTextJustification  or  it  can  insert  extra  spaces  between 
letters  with  SetTextCharacterExtra. 

Metafiles 

As  explained  earlier,  a  metafile  is  a  collection  of  GDI  function  calls  stored  in  a  binary 
coded  form.  A  program  can  create  a  metafile  by  calling  CreateMetaFile  and  giving  it  either 
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an  MS-DOS  filename  or  NULL  as  a  parameter.  If  CreateMetaFile  is  given  an  MS-DOS  file¬ 
name,  Windows  creates  a  disk-based  metafile;  if  the  parameter  is  NULL,  Windows  creates 
a  metafile  in  memory.  The  CreateMetaFile  call  returns  a  handle  to  a  metafile  device  con¬ 
text.  Any  GDI  calls  that  reference  this  device-context  handle  become  part  of  the  metafile. 

When  the  program  calls  CloseMetaFile,  Windows  closes  the  metafile  device  context  and 
returns  a  handle  to  the  metafile.  The  program  can  then  “play”  this  metafile  on  another 
device  context  (such  as  the  video  display)  without  calling  the  GDI  functions  directly. 

Metafiles  provide  a  useful  way  to  transfer  device-independent  pictures  between  programs. 


Data  Sharing  and  Data  Exchange 

Windows  includes  a  variety  of  methods  by  which  programs  can  share  and  exchange  data. 
These  methods  are  discussed  in  the  following  sections. 

Sharing  local  data  among  instances 

Multiple  instances  of  the  same  program  can  share  data  in  the  static  data  area  of  the  pro¬ 
gram’s  data  segment.  Later  instances  of  a  program  can  thus  call  GetInstanceData  and  copy 
configuration  options  established  by  the  user  in  the  first  instance.  Multiple  instances  of 
programs  can  also  share  resources,  such  as  dialog-box  templates. 

The  Windows  Clipboard 

The  Windows  Clipboard  is  a  general-purpose  mechanism  that  allows  a  user  to  transfer 
data  from  one  program  to  another.  Programs  that  support  the  Clipboard  generally  include 
a  top-level  menu  item  called  Edity  which  invokes  a  pop-up  menu  that  offers  at  least  these 
three  options: 

•  Cut:  Copies  the  current  selection  to  the  Clipboard  and  deletes  the  selection  from  the 
current  program  file. 

•  Copy:  Copies  the  current  selection  to  the  Clipboard  without  deleting  the  selection 
from  the  current  program  file. 

•  Paste:  Copies  the  contents  of  the  Clipboard  to  the  current  program  file. 

The  Clipboard  can  hold  only  one  item  at  a  time.  A  program  can  transfer  data  to  the  Clip¬ 
board  through  the  function  call  SetClipboardData.  With  this  function,  the  program  passes 
the  Clipboard  a  handle  to  a  global  memory  block,  which  then  becomes  the  property  of  the 
Clipboard.  A  program  can  access  Clipboard  data  through  the  complementary  function 
GetClipboardData. 

The  Clipboard  supports  several  formats: 

•  Text:  ASCII  text;  each  line  ends  with  a  carriage  return  and  linefeed,  and  the  text  is 
terminated  with  a  NULL  character. 

•  Bitmap:  A  collection  of  bits  in  the  GDI  bitmap  format. 
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•  Metafile  Picture:  A  structure  that  contains  a  handle  to  a  metafile  along  with  other 
information  suggesting  the  mapping  mode  and  aspect  ratio  of  the  picture. 

•  SYLK:  Microsoft’s  Symbolic  Link  format. 

•  DIF:  Software  Arts’  Data  Interchange  Format. 

Programs  can  also  use  the  Clipboard  for  storing  data  in  private  formats. 

Some  programs,  such  as  the  CLIPBRD  program  included  with  Windows,  can  also  become 
Clipboard  viewers.  Such  programs  receive  a  message  whenever  the  contents  of  the  Clip¬ 
board  change. 

Dynamic  Data  Exchange  (DDE) 

Dynamic  Data  Exchange  (DDE)  is  a  protocol  that  cooperating  programs  can  use  to 
exchange  data  without  user  intervention.  DDE  makes  use  of  the  facilities  in  Windows  that 
enable  programs  to  send  messages  among  themselves. 

In  DDE,  the  program  that  needs  data  from  another  program  is  called  the  client.  The  client 
sends  a  WM_DDE_JNITI ATE  message  either  to  a  dedicated  server  program  or  to  all  cur¬ 
rently  running  programs.  Parameters  to  the  WM__  DDE_  INITIATE  message  are  atoms, 
which  are  numbers  referring  to  text  strings.  A  server  application  that  has  the  data  the  client 
needs  sends  a  WM_DDE_ACK  message  back  to  the  client.  The  client  can  then  be  more 
specific  about  the  data  it  needs  by  sending  the  server  a  WM_DDE_  ADVISE  message.  The 
server  can  then  pass  global  memory  handles  to  the  client  with  the  WM_DDE_  DATA 
message. 


Internationalization 

Windows  includes  several  features  that  ease  the  conversion  and  translation  of  programs 
for  international  markets.  Among  these  features  are  keyboard  drivers  appropriate  for  many 
European  languages  and  use  of  the  ANSI  character  set,  which  provides  a  richer  set  of 
accented  letters  than  does  the  character  set  resident  in  the  IBM  PC  and  compatibles. 

Windows  also  includes  several  functions  that  assist  in  language-independent  coding.  The 
AnsiUpper  and  AnsiLower  functions  translate  characters  or  strings  to  uppercase  or  lower¬ 
case  in  the  full  ANSI  character  set,  rather  than  the  more  limited  ASCII  character  set.  In 
addition,  the  AnsiNext  and  AnsiPrev  functions  allow  scanning  of  text  strings  that  may 
contain  2  or  more  bytes  per  character. 

Windows  programmers  can  also  help  in  program  translation  by  defining  all  text  strings 
used  within  the  program  as  resources  contained  in  the  resource  script  file.  Because  the 
resource  script  file  also  contains  menu  templates  and  dialog-box  templates,  it  thus 
becomes  the  only  file  that  needs  alteration  when  a  foreign-language  version  of  the 
program  is  created. 


Charles  Petzold 
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Debugging  in  the  MS-DOS  Environment 


It  is  axiomatic  that  any  program  will  need  debugging  at  some  time  in  its  development 
cycle,  and  programs  written  to  run  under  MS-DOS  are  no  exception.  This  article  provides 
an  introduction  to  the  debugging  tools  and  techniques  available  to  the  serious  program¬ 
mer  developing  code  in  the  MS-DOS  environment.  Space  does  not  permit  a  thorough 
investigation  of  the  philosophy,  psychology,  and  science  of  debugging  computer  pro¬ 
grams;  instead,  a  brief  and  practical  discussion  of  the  basic  debugging  approaches  is  pre¬ 
sented,  along  with  some  rules-of-thumb  for  choosing  the  best  approach.  Nor  are  the  details 
of  every  single  utility  and  command  included  in  this  article;  these  are  described  in  detail 
in  the  reference  sections  of  this  volume.  The  commands  and  utility  programs  that  are 
most  useful  for  debugging  are  discussed  and  illustrated  with  examples  and  case  histories 
that  also  serve  as  models  for  the  various  debugging  methods. 

The  reader  of  this  article  is  assumed  to  be  a  programmer  with  sufficient  experience  to 
understand  an  assembly-language  program.  The  reader  is  also  assumed  to  be  familiar  with 
MS-DOS — terms  like  FCB  and  PSP  are  not  explained.  A  reader  without  this  background  in 
MS-DOS  need  not  be  deterred,  however;  these  terms  are  thoroughly  explained  elsewhere 
in  this  book.  Besides  assembly  language,  examples  in  this  article  are  written  in  Microsoft 
QuickBASIC  and  Microsoft  C.  A  detailed  knowledge  of  these  languages  is  not  required;  the 
examples  are  short  and  straightforward. 

The  reader  should  also  keep  in  mind  that  the  examples  given  here  are  real  but  not  neces¬ 
sarily  realistic.  To  avoid  the  tedium  that  accompanies  debugging,  the  examples  have  been 
designed  to  reveal  their  bugs  fairly  quickly.  All  the  methods  and  techniques  shown  are 
accurate  in  detail  but  not  always  in  scale.  Most  of  the  debugging  examples  presented  here 
would  require  one-half  to  one  hour  of  work.  It  is  possible  for  real  debugging  sessions  to 
last  for  hours  or  days,  especially  if  the  wrong  approach  or  tool  is  chosen.  One  of  the  pur¬ 
poses  of  this  article  is  to  help  the  programmer  choose  the  correct  tool  and,  thus,  to  reduce 
the  tedium. 


The  Programs 

There  are  more  than  a  dozen  listings  in  this  article.  Some  of  them  are  correct  and  others 
contain  errors  for  use  in  illustrating  debugging  techniques.  Many  of  the  programs  serve 
as  examples  in  multiple  sections  of  the  article.  The  following  summary  of  the  programs 
(Table  18-1)  is  given  to  avoid  confusion  and  to  provide  a  common  location  to  consult  for 
explanations  of  the  programs. 
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Table  18>1.  Summary  of  Example  Programs. 


Name: 

EXP.BAS 

Figure: 

18-1 

Status: 

Incorrect — do  not  use. 

Purpose: 

Computes  EXPix)  (the  exponential  of  x)  to  a  specified  precision  using  an 

infinite  series. 

Compiling: 

QB  EXP; 

LINK  EXP; 

Parameters: 

Prompts  for  value  for  x  and  a  convergence  criterion.  Enter  zero  to  quit. 

Name: 

Figure: 

Status: 

Purpose: 

Compiling: 

Parameters: 


EXP.BAS 

18-3 

Correct  version  of  Figure  18-1. 

Computes  EXP(jc)  (the  exponential  of  x)  to  a  specified  precision  using  an 
infinite  series. 

QBEXP; 

LINK  EXP; 

Prompts  for  value  for  x  and  a  convergence  criterion.  Enter  zero  to  quit. 


Name: 

Figure: 

Status: 

Purpose: 


Compiling: 


Parameters: 


COMMSCORASM 

18-4 

Correct. 

Monitors  the  activity  on  a  specified  COM  port  and  places  a  copy  of  all 
transmitted  and  received  data  in  a  RAM  buffer.  Each  entry  in  the  buffer  is 
tagged  to  indicate  whether  the  byte  was  sent  by  or  received  by  the  applica¬ 
tion  program  under  test.  Control  is  provided  to  start,  stop,  and  resume  trac¬ 
ing  by  means  of  a  control  interrupt.  When  tracing  is  stopped  and  resumed, 
a  marker  is  left  in  the  buffer.  COMMSCOP  is  a  terminate-and-stay-resident 
(TSR)  program. 

MASM  COMMSCOP; 

LINK  COMMSCOP; 

EXE2BIN  COMMSCOP.EXE  COMMSCOP.COM 
DEL  COMMSCOP.EXE 

Installed  by  entering  COMMSCOP’,  no  parameters  for  installation.  The 
TSR  is  controlled  by  passing  parameter  data  in  registers  with  an  Interrupt 
60H  call.  The  registers  can  have  the  following  values: 

AH:  Command: 

OOH  STOP 

OlH  FLUSH  AND  START 

02H  RESUME  TRACE 

03H  RETURN  TRACE  BUFFER  ADDRESS 


(more) 
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DX: 

COM  port: 

OOH 

COMl 

OlH 

COM2 

Interrupt  60H  returns  the  following  in  response  to  function  3: 

CX  Buffer  count  in  bytes 

DX  Segment  address  of  buffer 

BX  Offset  address  of  buffer 


Name: 

Figure: 

Status: 

Purpose: 

COMPILING: 

Parameters: 


COMMSCMD.C 

18-5 

Correct. 

Controls  the  COMMSCOP  program  by  issuing  Interrupt  60H  calls. 

C  version. 

MSCCOMMSCMD; 

LINKCOMMSCMD; 

Commands  are  issued  by 

COMMSCMD  [[cmd\[  port]] 

where:  cmd  is  the  command  to  be  executed: 

STOP  Stop  trace 

START  Flush  buffer  and  start  trace 

RESUME  Resume  a  stopped  trace 
port  is  the  COM  port  (1  =  COMl,  2  =  COM2) 

If  cmd  is  omitted,  STOP  is  assumed;  if  port  is  omitted,  1  is  assumed. 


Name: 

Figure: 

Status: 

Purpose: 

Compiling: 

Parameters: 


COMMSCMD.BAS 

18-6 

Correct. 

Controls  the  COMMSCOP  program  by  issuing  Interrupt  60H  calls. 
QuickBASIC  version. 

QB  COMMSCMD; 

LINK  COMMSCMD  USERLIB; 

Commands  are  issued  by 

COMMSCMD  [[cmd]lport]] 

where:  cmd  is  the  command  to  be  executed: 

STOP  Stop  trace 

START  Flush  buffer  and  start  trace 

RESUME  Resume  a  stopped  trace 
port  is  the  COM  port  (1  =  COMl,  2  =  COM2) 

If  cmd  is  omitted,  STOP  is  assumed;  if  port  is  omitted,  1  is  assumed. 


Name  COMMDUMP.BAS 

Figure:  18-7 

Status:  Correct. 

Purpose:  Produces  a  formatted  dump  of  the  communications  trace  buffer. 


(more) 
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Compiling:  QB  COMMDUMP; 

LINK  COMMDUMP  USERLIB; 

Parameters:  No  parameters.  When  COMMDUMP  is  invoked,  it  formats  and  dumps  the 

entire  buffer. 


Name: 

Figure: 

Status: 

Purpose: 

Compiling: 

Parameters: 


TESTCOMM.ASM 

18-9 

Incorrect — do  not  use. 

Provides  test  data  for  the  COMMSCOP  routine. 

MASMTESTCOMM; 

LINKTESTCOMM; 

No  parameters.  TESTCOMM  reads  data  from  the  keyboard  and  writes  to 
COMl  and  reads  COMl  data  and  displays  it  on  the  screen.  Ctrl-C  cancels. 


Name: 

Figure: 

Status: 

Purpose: 

Compiling: 

Parameters: 


TESTCOMM.ASM 

18-10 

Correct  version  of  Figure  18-9. 

Provides  test  data  for  the  COMMSCOP  routine. 

MASMTESTCOMM; 

LINKTESTCOMM; 

No  parameters.  TESTCOMM  reads  data  from  the  keyboard  and  writes  to 
COMl  and  reads  COMl  data  and  displays  it  on  the  screen.  Ctrl-C  cancels. 


Name: 

Figure: 

Status: 

Purpose: 


Compiling: 


Parameters: 


BADSCOP.ASM 

18-11 

Incorrect  version  of  Figure  18-4 — do  not  use. 

Monitors  the  activity  on  a  specified  COM  port  and  places  a  copy  of  all 
transmitted  and  received  data  in  a  RAM  buffer.  Each  entry  in  the  buffer  is 
tagged  to  indicate  whether  the  byte  was  sent  by  or  received  by  the  applica¬ 
tion  program  under  test.  Control  is  provided  to  start,  stop,  and  resume  trac¬ 
ing  by  means  of  a  control  interrupt.  When  tracing  is  stopped  and  resumed, 
a  marker  is  left  in  the  buffer.  BADSCOP  is  a  terminate-and-stay-resident 
(TSR)  program. 

MASM  BADSCOP; 

LINK  BADSCOP; 

EXE2BIN  BADSCOP.EXE  BADSCOP.COM 
DELBADSCOP.EXE 

Installed  by  entering  BADSCOP  \  no  parameters  for  installation.  The  TSR  is 
controlled  by  passing  parameter  data  in  registers  with  an  Interrupt  60H 
call.  The  registers  can  have  the  following  values: 


AH: 

Command: 

OOH 

STOP 

OlH 

FLUSH  AND  START 

(more) 
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02H 

RESUME  TRACE 

03H 

RETURN  TRACE  BUFFER  ADDRESS 

DX: 

COM  port: 

OOH 

COMl 

OlH 

COM2 

Interrupt  60H  returns  the  following  in  response  to  function  3: 

CX 

Buffer  count  in  bytes 

DX 

Segment  address  of  buffer 

BX 

Offset  address  of  buffer 

Name: 

Figure: 

Status: 

Purpose: 

Compiling: 

Parameters: 

UPPERCAS.C 

18-13 

Incorrect — do  not  use. 

Converts  a  fixed  string  to  uppercase  and  prints  it. 

MSC/ZiUPPERCAS; 

LINKUPPERCAS/CO; 

No  parameters. 

Name: 

UPPERCAS.C 

Figure: 

18-14 

Status: 

Correct  version  of  Figure  18-13. 

Purpose: 

Converts  a  fixed  string  to  uppercase  and  prints  it. 

Compiling: 

MSC/ZiUPPERCAS; 

LINKUPPERCAS/CO; 

Parameters: 

No  parameters. 

Name: 

ASCTBLC 

Figure: 

18-16 

Status: 

Incorrect — do  not  use. 

Purpose: 

Displays  a  table  of  all  displayable  characters. 

Compiling: 

MSC/ZiASCTBL; 

LINKASCTBL/CO; 

Parameters: 

No  parameters. 

Name: 

ASCTBL.C 

Figure: 

18-17 

Status: 

Correct  version  of  Figure  18-16. 

Purpose: 

Displays  a  table  of  all  displayable  characters. 

Compiling: 

MSC/ZiASCTBL; 

LINKASCTBL/CO; 

Parameters: 

No  parameters. 
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Debugging  Tools  and  Techniques 

MS-DOS  provides  a  wide  variety  of  tools  to  aid  in  the  debugging  process.  Some  are 
intended  specifically  for  debugging.  For  example,  the  DEBUG  program  is  delivered  with 
MS-DOS  and  provides  basic  debugging  aid;  the  more  sophisticated  SYMDEB  is  supplied 
with  MASM,  Microsoft’s  macro  assembler;  CodeView,  a  debugger  for  high-order  languages, 
is  supplied  with  Microsoft  C,  Microsoft  Pascal,  and  Microsoft  FORTRAN.  Others  are  gen¬ 
eral  MS-DOS  services  and  features  that  are  also  useful  in  the  debugging  process. 

Debugging,  like  programming,  has  aspects  of  both  an  art  and  a  craft.  The  craft — the 
mechanical  details  of  using  the  tools — is  discussed  both  here  and  elsewhere  in  this 
volume,  but  the  main  subject  of  this  article  is  the  art  of  debugging — the  choice  of  the 
correct  tool,  the  best  techniques  to  use  in  various  situations,  the  methods  of  extracting  the 
clues  to  the  problem  from  a  recalcitrant  program. 

Debugging  a  program  is  a  form  of  puzzle  solving.  As  with  most  intellectual  detective 
work,  the  following  rule  applies: 

Gather  enough  information  and  the  solution  will  be  obvious. 

The  craft  of  debugging  involves  gathering  the  data;  the  art  lies  in  deciding  which  data  to 
gather  and  in  noticing  when  the  solution  has  become  obvious. 

The  methods  of  gathering  data  for  debugging,  listed  in  order  of  increasing  difficulty  and 
tediousness,  fall  into  four  major  categories: 

•  Inspection  and  observation 

•  Instrumentation 

•  Use  of  software  debugging  monitors  (DEBUG,  SYMDEB,  and  CodeView) 

•  Use  of  hardware  debugging  aids 

As  mentioned  above,  part  of  the  art  of  debugging  is  knowing  which  method  to  use.  This 
is  one  of  the  most  difficult  aspects  of  debugging — so  difficult,  in  fact,  that  even  program¬ 
mers  with  years  of  experience  make  mistakes.  Many  programmers  have  spent  hours 
single-stepping  through  a  program  with  DEBUG  only  to  discover  that  the  cause  of  the 
problem  would  have  been  obvious  if  they  had  given  the  program’s  output  even  a  cursory 
check.  The  only  universal  rule  for  choosing  the  correct  debugging  method  is 

Try  them  ally  starting  with  the  simplest. 

Inspection  and  observation 

Inspection  and  observation  is  the  oldest  and,  usually,  the  best  method  of  program  debug¬ 
ging.  It  is  also  the  basis  for  all  the  other  methods.  The  first  step  with  this  method,  as  with 
the  others,  is  to  gather  all  the  pertinent  materials.  Program  listings,  file  layouts,  report 
layouts,  and  program  design  materials  (such  as  algorithm  descriptions  and  flowcharts) 
are  all  extremely  valuable  in  the  debugging  process. 
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Desk-checking 

Before  a  programmer  can  determine  what  a  program  is  doing  wrong,  he  or  she  must 
know  the  correct  operation  of  the  program.  There  was  a  time,  when  computers  were  rare 
and  expensive  resources,  that  programmers  were  encouraged  not  to  run  their  programs 
until  the  programs  had  been  thoroughly  desk-checked.  The  desk-checking  process  in¬ 
volves  sitting  down  with  a  listing,  a  hand  calculator,  and  some  sample  data.  The  program¬ 
mer  then  “plays  computer,”  executing  each  line  of  the  program  manually  and  writing 
down  on  paper  the  results  of  each  program  step.  This  process  is  extremely  slow  and 
tedious.  When  the  desk-checking  is  completed,  however,  the  programmer  not  only  has 
found  most  of  the  bugs  in  the  program  but  also  has  become  intimately  familiar  with  the 
execution  of  the  program  and  the  values  of  the  program  variables  at  each  step. 

The  advent  of  inexpensive  yet  powerful  personal  computers,  combined  with  the  rising 
cost  of  programmer  time,  has  made  complete  desk-checking  nearly  obsolete.  It  is  now 
cheaper  to  run  the  program  and  let  the  computer  find  the  errors.  However,  the  usefulness 
of  the  desk-checking  technique  remains.  Many  programmers  find  it  helpful  to  manually 
execute  those  sections  of  a  program  that  they  suspect  are  causing  trouble.  Even  if  they 
don’t  find  errors  in  the  code,  the  insight  they  gain  into  the  workings  of  the  code  and  the 
values  of  the  variables  at  each  step  can  be  invaluable  when  applying  other  debugging 
techniques. 

The  inspection-and-observation  methodology 

The  basic  technique  of  the  inspection-and-observation  method  is  simple:  After  gathering 
all  the  required  materials,  run  the  program  and  observe.  Observe  very  carefully;  events 
that  seem  insignificant  may  be  the  very  clues  needed  to  discover  where  the  program  is 
going  astray.  As  the  program  executes,  note  whether  each  section  performs  correctly. 
Does  the  program  clear  the  screen  when  it  should?  Does  it  ask  for  input  when  it  should? 
Does  it  produce  the  correct  results?  Observable  events  are  the  debugger’s  milestones  in 
the  execution  of  the  program.  If  the  program  clears  the  screen  but  writes  purple  asterisks 
instead  of  requesting  input,  then  the  problem  lies  somewhere  after  the  program  issues  the 
Clear  Screen  command  but  before  it  writes  the  input  prompt  on  the  screen.  At  this  point, 
the  program  listing  and  design  data  become  important.  Inspect  the  listing  and  examine 
the  area  after  the  last  successful  milestone  and  before  the  missing  milestone.  Look  for  a 
logic  error  in  the  code  that  could  explain  the  observed  data. 

If  the  program  produces  printed  reports,  they  may  also  be  useful.  Watch  the  screen  and 
listen  to  the  printer.  Clues  can  sometimes  be  found  in  the  order  in  which  things  happen. 
The  light  on  the  disk  drive  can  be  another  indication  of  activity.  See  how  disk  activity  co¬ 
ordinates  with  screen  and  printer  events.  Try  to  identify  each  section  of  the  program  from 
these  clues.  Then  use  this  information  to  localize  the  inspection  of  the  listing  to  isolate 
the  erroneous  code. 

The  values  of  data  given  in  reports  and  on  the  screen  can  also  give  clues  to  what’s  going 
wrong.  Examining  the  data  and  reconstructing  the  values  used  to  compute  it  sometimes 
leads  to  inferences  about  data  problems.  Perhaps  a  variable  was  misspelled  in  the  code 
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or  perhaps  a  data  file  is  in  the  wrong  format  or  has  been  corrupted.  With  this  information, 
the  bug  can  often  be  isolated.  However,  a  very  thorough  knowledge  of  the  program  and  its 
algorithms  is  required.  See  Desk-checking  above. 

MS-DOS  provides  four  commands  and  filters  that  are  useful  in  the  collection  and  examina¬ 
tion  of  data  for  debugging:  TYPE,  PRINT,  FIND,  and  DEBUG.  All  these  commands  display 
the  data  in  a  file  in  some  way.  If  the  data  is  ASCII  (displayable)  characters,  TYPE  and 
PRINT  can  be  used,  with  some  help  from  FIND.  Binary  files  can  be  examined  and  modi¬ 
fied  with  the  DEBUG  utility.  See  USER  COMMANDS:  find;  print;  type;  PROGRAMMING 
UTILITIES:  debug. 

The  TYPE  command  provides  the  simplest  way  to  display  ASCII  data  files.  This  method 
can  be  used  to  examine  both  input  and  output  files.  Checking  the  input  files  may  uncover 
some  bad  (or  unexpected)  data  that  causes  the  program  to  malfunction;  examining  the 
output  files  will  show  whether  calculations  are  being  performed  correctly  and  may  help 
pinpoint  the  erroneous  calculations  if  they  are  not. 

The  FIND  utility  is  useful  in  locating  specific  data  in  a  file.  Using  FIND  is  more  accurate 
and  definitely  less  tedious  than  examining  the  file  manually  using  the  TYPE  command. 
The  /N  switch  causes  FIND  to  also  display  the  relative  line  number  of  the  matching  line — 
information  that  is  most  useful  in  debugging. 

Sometimes  the  data  is  too  complex  to  be  examined  on  the  screen  and  printed  copy  is 
needed.  The  PRINT  command  will  produce  hard  copy  of  an  ASCII  file  as  will  the  TYPE 
command  if  its  output  is  redirected  to  the  printer  with  the  >PRN  command-line  parameter 
after  the  filename. 

Not  all  data  files  contain  pure  ASCII  data,  and  displaying  such  non-ASCII  files  requires  a 
different  approach.  The  TYPE  command  can  be  used,  but  nonprintable  characters  will 
produce  garbage  on  the  screen.  This  technique  can  still  prove  useful  if  the  file  has  a  large 
amount  of  ASCII  data  or  if  the  records  are  regular  and  the  ASCII  information  always 
appears  at  the  same  location,  but  no  information  can  be  gained  about  non-ASCII  numeric 
data  in  such  files.  Note  also  that  the  entire  file  might  not  be  displayed  using  TYPE  because 
if  TYPE  encounters  a  byte  containing  lAH  (Control-Z),  it  assumes  it  has  reached  the  end 
of  the  file  and  stops. 

Clearly,  a  more  useful  tool  for  examining  non-ASCII  files  would  be  a  program  that  dumps 
the  file  in  hexadecimal,  with  an  appropriate  translation  of  all  displayable  characters.  Such 
programs  exist  in  the  public  domain  (through  bulletin-board  services,  for  instance)  and,  in 
any  event,  are  not  difficult  to  write.  MS-DOS  does  not  include  a  stand-alone  file-dumping 
program  among  its  standard  commands  and  utilities,  but  the  DEBUG  program  can  be 
used,  with  minor  inconvenience,  to  display  files.  This  program  is  discussed  in  detail  later 
in  this  article;  for  now,  simply  follow  these  instructions  to  use  DEBUG  as  a  file  dumper. 

To  load  DEBUG  and  the  program  to  be  debugged,  use  the  form 

DEBUG  [drive'][path]  filename. ext 

DEBUG  will  display  a  hyphen  as  a  prompt.  To  see  the  contents  of  the  file,  enter  D  (the 
DEBUG  Display  Memory  command)  and  press  Enter.  DEBUG  will  display  the  first  128 
(80H)  bytes  of  the  file  in  hexadecimal  and  will  also  show  any  displayable  characters. 
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To  see  the  rest  of  the  file,  simply  continue  entering  D  until  the  desired  area  is  found.  Hard 
copy  of  the  contents  of  the  display  can  be  made  by  using  the  PrtSc  key  (or  Ctrl-PrtSc  to 
print  continuously).  Note  that  the  offset  addresses  for  the  bytes  in  the  file  begin  at  the 
value  in  the  program’s  CS:IP  registers,  which  can  be  viewed  by  using  the  Debug  R  (Display 
or  Modify  Registers)  command.  To  obtain  the  true  offsets,  subtract  CS:IP  from  the  address 
shown. 

The  essence  of  the  inspection-and-observation  method  is  careful  and  thoughtful  observa¬ 
tion.  The  computer  and  the  operating  system  can  provide  tools  to  aid  in  the  collection  of 
data,  but  the  most  important  tool  is  the  programmer’s  mind.  By  applying  the  logical  skills 
they  already  possess  to  the  observed  data,  programmers  can  usually  avoid  the  more 
complex  forms  of  debugging. 

Instrumentation 

Debugging  by  instrumentation  is  a  traditional  method  that  has  been  popular  since  pro¬ 
grams  were  holes  punched  in  cards.  In  general,  this  method  consists  of  adding  something 
to  the  program,  either  internally  or  externally,  to  report  on  the  progress  of  program  execu¬ 
tion.  Programmers  call  this  added  mechanism  instrumentation  because  of  its  resemblance 
to  the  measuring  instruments  used  in  science  and  engineering.  Instrumentation  can  be 
software,  hardware,  or  a  combination  of  both;  it  can  be  internal  to  the  program  or  external 
to  it.  Internal  instrumentation  is  always  software,  but  external  instrumentation  may  be 
either  hardware  or  software. 

Internal  instrumentation 

Internal  instrumentation  usually  consists  of  display  or  print  statements  placed  at  strategic 
locations.  Other  signals  to  the  user  can  be  used  if  they  are  available.  For  instance,  the  sys¬ 
tem  beeper  can  be  sounded  at  key  locations,  perhaps  in  a  coded  sequence  of  beeps;  if  the 
device  being  debugged  has  lights  that  can  be  accessed  by  the  program,  these  lights  can  be 
flashed  at  important  locations  in  the  program.  Beeping  and  flashing  do  not,  however, 
possess  the  information  content  usually  required  for  debugging,  so  display  or  print  state¬ 
ments  are  preferred. 

The  use  of  display  or  print  statements  to  display  key  data  and  milestones  on  the  screen  or 
printer  requires  careful  planning.  First,  apply  the  techniques  of  inspection  and  observation 
described  in  the  previous  section  to  determine  the  most  probable  points  of  failure.  Then,  if 
there  is  some  doubt  about  what  path  execution  is  taking  through  the  code,  embed  mes¬ 
sages  of  the  following  types  after  key  decision  points: 

BEGINNING  SORT  PHASE 
ENDING  PRINCIPAL  CALCULATION 
PROCESSING  RECORD  XX 

A  second  way  to  use  display  or  print  statement  instrumentation  is  to  embed  statements  that 
display  the  data  and  interim  values  used  for  calculations.  This  technique  can  be  extremely 
useful  in  finding  problems  related  to  the  data  being  processed.  Consider  the  QuickBASIC 
program  in  Figure  18-1  as  an  example.  The  program  has  no  syntax  errors  and  compiles 
cleanly,  but  it  sometimes  produces  an  incorrect  answer. 
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EXP. BAS  —  COMPUTE  EXPONENTIAL  WITH  INFINITE  SERIES 


* 

*  EXP 

* 

*  This  routine  computes  EXP(x)  using  the  following  infinite  series: 

* 

*  X  x'"2  x'^3  x''4  x‘^5 

*  EXP(x)  =  1  + - + - + - + - + - +  ... 

*  1  !  2 !  3 !  4 !  5 ! 

* 

* 

*  The  program  requests  a  value  for  x  and  a  value  for  the  convergence 

*  criterion,  C.  The  program  will  continue  evaluating  the  terms  of 

*  the  series  until  the  difference  between  two  terms  is  less  than  C. 

* 

*  The  result  of  the  calculation  and  the  number  of  terms  required  to 

*  converge  are  printed.  The  program  will  repeat  until  an  x  of  0  is 

*  entered. 

* 


♦  ♦ 
* 
♦ 
* 
* 
* 
* 
* 
* 
* 
* 
* 
♦ 
♦ 
♦ 
* 
* 
* 
* 


HiHtitiitsi^******HiHi4i******************************************************** 


Initialize  program  variables 


INITIALIZE: 

TERMS  =  1 
FACT  =  1 
LAST  =  1.E35 
DELTA  =  1 .E34 
EX  =  1 


'  Input  user  data 

I 

INPUT  "Enter  number:  X 

IF  X  =  0  THEN  END 

INPUT  "Enter  convergence  criterion  (.0001  for  4  places):  ";  C 


'  Compute  exponential  until  difference  of  last  2  terms  is  <  C 

WHILE  ABS(LAST  -  DELTA)  >=  C 
LAST  =  DELTA 
FACT  =  FACT  *  TERMS 
DELTA  =  X'^TERMS  /  FACT 
EX  =  EX  +  DELTA 
TERMS  =  TERMS  +  1 

WEND 

Figure  18-1.  A  routine  to  compute  exponentials. 


(more) 
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'  Display  answer  and  number  of  terms  required  to  converge 

I 

PRINT  EX 

PRINT  TERMS;  "elements  required  to  converge" 

PRINT 

GOTO  INITIALIZE 

Figure  18-1.  Continued. 

The  purpose  of  the  EXP.BAS  program  is  to  compute  the  exponential  of  a  given  number 
to  a  specified  precision  using  an  infinite  series.  The  program  computes  the  value  of  each 
term  in  the  infinite  series  and  adds  it  to  a  running  total.  To  keep  from  executing  forever, 
the  program  checks  the  difference  between  the  last  two  elements  computed  and  stops 
when  this  difference  is  less  than  the  convergence  criterion  entered  by  the  user. 

When  the  program  is  run  for  several  values,  the  following  results  are  observed: 

Enter  number:  ?  1 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
2.718282 

1 0  elements  required  to  converge 
Enter  number:  ?  1.5 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
4.481686 

1 1  elements  required  to  converge 
Enter  number:  ?  2 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
5 

3  elements  required  to  converge 
Enter  number:  ?  2.5 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
12.18249 

1 5  elements  required  to  converge 
Enter  number:  ?  3 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
13 

4  elements  required  to  converge 
Enter  number:  ?  0 

Some  of  these  numbers  are  incorrect.  Table  18-2  shows  the  computed  values  and  the 
correct  values. 
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Table  18-2.  The  Computed  Values  Generated  by  EXP.BAS  and  the  Expected 


Values. 

X 

Computed 

Correct 

1.0 

2.718282 

2.718282 

1.5 

4.481686 

4.481689 

2.0 

5 

7.389056 

2.5 

12.18249 

12.18249 

3.0 

13 

20.08554 

Applying  the  methods  from  the  first  section  of  this  article  and  observing  the  data  quickly 
reveals  a  pattern.  With  the  exception  of  1,  all  whole  numbers  give  incorrect  results,  but  all 
numbers  with  fractions  give  results  that  are  correct  to  the  specified  convergence  criterion. 
Examination  of  the  listing  shows  no  obvious  reason  for  this.  The  answer  is  there,  but  only 
an  exceptionally  intuitive  numeric  analyst  would  see  it.  Because  no  answer  is  obvious,  the 
next  step  is  to  validate  the  only  information  available — that  whole  numbers  produce  er¬ 
rors  and  fractional  ones  do  not.  Repeating  the  first  experiment  with  2  and  a  number 
very  close  to  2  yields  the  following  results: 

Enter  number:  ?  1.999 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
7.38167 

1 3  elements  required  to  converge 
Enter  number:  ?  2 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
5 

3  elements  required  to  converge 
Enter  number:  ?  0 

The  outcome  is  the  same — repeating  the  experiment  with  a  number  as  near  to  2  as  the 
convergence  criterion  permits  (1.9999)  produces  the  same  result.  The  error  is  indeed 
caused  by  the  fact  that  the  number  is  an  integer. 

Because  no  intuitive  way  can  be  found  to  solve  the  mystery  by  inspection,  the  program¬ 
mer  must  turn  to  the  next  method  in  the  hierarchy,  instrumentation.  The  problem  has 
something  to  do  with  the  calculation  of  the  terms  of  the  series.  Therefore,  the  section  of 
the  program  that  performs  this  calculation  should  be  instrumented  by  placing  PRINT 
statements  inside  the  WHILE  loop  (Figure  18-2)  to  display  all  the  intermediate  values 
of  the  calculation. 

WHILE  ABS(LAST  -  DELTA)  >=  C 
LAST  =  DELTA 
FACT  =  FACT  *  TERMS 
DELTA  =  X  TERMS  /  FACT 

Figure  18-2.  Instrumenting  the  WHILE  loop.  (more) 
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EX  =  EX  +  DELTA 

PRINT  "TERMS=";  TERMS;  ”EX=*';  EX;  ''FACT=”;  FACT;  "DELTA=";  DELTA; 

PRINT  "LAST=";  LAST 
TERMS  =  TERMS  +  1 

WEND 

Figure  18-2.  Continued. 

The  print  statements  used  in  this  WHILE  loop  are  typical  of  the  type  used  for  instrumenta¬ 
tion.  The  program  makes  no  attempt  at  fancy  formatting.  The  print  statements  simply 
identify  each  value  with  its  variable  name,  allowing  easy  correlation  of  the  data  and  the 
code  in  the  listing.  Repeating  the  experiment  with  1.999  and  2  yields 

Enter  number:  ?  1.999 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
TERMS=  1  EX=  2.999  FACT=  1  DELTA=  1.999  LAST=  1E+34 
TERMS=  2  EX=  4.997001  FACT=  2  DELTA=  1.998  LAST=  1.999 

TERMS=  3  EX=  6.328335  FACT=  6  DELTA=  1.331334  LAST=  1.998 

TERMS=  4  EX=  6.993669  FACT=  24  DELTA=  .6653343  LAST=  1.331334 

TERMS=  5  EX=  7.25967  FACT=  120  DELTA=  .2660006  LAST=  .6653343 

TERMS=  6  EX=  7.348292  FACT=  720  DELTA=  8.862254E-02  LAST=  .2660006 
TERMS=  7  EX=  7.373601  FACT=  5040  DELTA=  2.530806E-02  LAST=  8.862254E-02 
TERMS=  8  EX=  7.379924  FACT=  40320  DELTA=  6.323853E-03  LAST=  2.530806E-02 
TERMS=  9  EX=  7.381329  FACT=  362880  DELTA=  1 .404598E-03  LAST=  6.323853E-03 
TERMS=  10  EX=  7.38161  FACT=  3628800  DELTA=  2.807791E-04  LAST=  1.404598E-03 
TERMS=  11  EX=  7.381661  FACT=  3.991 68E+07  DELTA=  5.102522E-05  LAST=  2. 807791 E-04 
TERMS=  12  EX=  7.38167  FACT=  4.790016E+08  DELTA=  8.499951E-06  LAST=  5.102522E-05 
7.38167 

1 3  elements  required  to  converge 
Enter  number:  ?  2 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
TERMS=  1  EX=  3  FACT=  1  DELTA=  2  LAST=  1E+34 
TERMS=  2  EX=  5  FACT=  2  DELTA=  2  LAST=  2 
5 

3  elements  required  to  converge 

Examination  of  the  instrumentation  printout  for  the  two  cases  shows  a  drastically  different 
pattern.  The  fractional  number  went  through  13  iterations  following  the  expected  pattern; 
the  whole  number,  however,  quit  on  the  third  step.  The  loop  is  terminating  prematurely. 
Why?  Look  at  the  values  calculated  for  DELTA  and  LAST  on  the  last  complete  step.  They 
are  the  same,  giving  a  difference  of  zero.  Because  this  difference  will  always  be  less  than 
the  convergence  criterion,  the  loop  will  always  terminate  early.  A  moment’s  reflection 
shows  why.  The  numerator  of  the  fraction  for  each  term  but  the  first  in  the  infinite  series  is 
a  power  of  the  number  entered;  the  denominator  is  a  factorial,  a  product  formed  by  multi¬ 
plying  successive  integers.  Because  n\  =  n ♦(w-1)!,  when  an  integer  is  raised  to  a  power 
equal  to  itself  and  divided  by  the  factorial  of  that  integer  the  result  will  always  be  the  same 
as  the  preceding  term.  That  is  what  has  happened  here. 
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Now  that  the  cause  of  the  problem  is  found,  it  must  be  fixed.  How  can  this  problem  be 
preventecf  In  this  case,  the  problem  is  caused  by  a  logic  error.  The  programmer  misread 
(or  miswrote!)  the  algorithm  and  assumed  that  the  criterion  for  termination  was  that  the 
difference  between  the  last  two  terms  be  less  than  the  specified  value.  This  is  incorrect. 
Actually,  the  termination  criterion  should  be  that  the  difference  between  the  forming 
EXP(.j(r)  and  the  last  term  be  less  than  the  criterion.  To  simplify,  the  last  term  itself  must  be 
less  than  the  value  specified.  The  correct  program  listing,  including  the  new  WHILE  loop, 
is  shown  in  Figure  18-3. 


EXP. BAS  —  COMPUTE  EXPONENTIAL  WITH  INFINITE  SERIES 

********************************************************************** 
*  * 

*  EXP  * 

*  * 

*  This  routine  computes  EXP(x)  using  the  following  infinite  series:  * 

*  * 

*  X  x'^2  x''3  x''4  x^5  * 

*  EXP(x)  =  1  + - + - + - + - + - +  ...  * 

*  1!2!3!4!5!  * 

* 

«  ♦ 

*  The  program  requests  a  value  for  x  and  a  value  for  the  convergence  * 

*  criterion,  C.  The  program  will  continue  evaluating  the  terms  of  * 

*  the  series  until  the  amount  added  with  a  term  is  less  than  C.  * 

:|c  * 

*  The  result  of  the  calculation  and  the  number  of  terms  required  to  * 

*  converge  are  printed.  The  program  will  repeat  until  an  x  of  0  is  * 

*  entered.  * 

*  * 


'  Initialize  program  variables 

I 

INITIALIZE: 

TERMS  =  1 
FACT  =  1 
DELTA  =  1 .E35 

EX  =  1  ^ 

f 

'  Input  user  data 

INPUT  "Enter  number:  X 

IF  X  =  0  THEN  END 

INPUT  "Enter  convergence  criterion  (.0001  for  4  places):  ";  C 


'  Compute  exponential  until  difference  of  last  2  terms  is  <  C 


Figure  18-3-  Corrected  exponential  calculation  routine. 


(more) 
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WHILE  DELTA  >  C 

FACT  =  FACT  *  TERMS 
DELTA  =  X^TERMS  /  FACT 
EX  =  EX  +  DELTA 
TERMS  =  TERMS  +  1 

WEND 


'  Display  answer  and  nuinber  of  terms  required  to  converge 

I 

PRINT  EX 

PRINT  TERMS;  "elements  required  to  converge" 

PRINT 

GOTO  INITIALIZE 
Figure  18-3.  Continued. 

The  program  now  produces  the  correct  results  within  the  limits  of  the  specified  accuracy: 

Enter  number:  ?  1.999 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
7.381661 

12  elements  required  to  converge 
Enter  number:  ?  2 

Enter  convergence  criterion  (.0001  for  4  places):  ?  .0001 
7.389047 

12  elements  required  to  converge 
Enter  number:  ?  0 

This  example  illustrates  how  easy  it  is  to  use  internal  instrumentation  in  high-order  lan¬ 
guages.  Because  these  languages  usually  have  simple  formatted  output  commands,  they 
require  very  little  work  to  instrument.  When  these  output  commands  are  not  available, 
however,  more  work  may  be  required.  For  instance,  if  the  program  being  debugged  is  in 
assembly  language,  it  is  possible  that  the  code  required  to  format  and  print  internal  data 
will  be  longer  than  the  program  being  debugged.  For  this  reason,  internal  instrumentation 
is  rarely  used  on  small  and  moderate  assembly  programs.  However,  large  assembly  pro¬ 
grams  and  systems  often  already  have  print  formatting  routines  built  into  them;  in  these 
cases,  internal  instrumentation  may  be  as  easy  as  with  high-order  languages. 

External  instrumentation 

Sometimes  it  is  difficult  to  use  internal  instrumentation  with  a  program.  If,  for  instance, 
the  problem  is  timing  related,  adding  print  statements  could  cloud  the  problem  or,  worse 
yet,  make  it  go  away  completely.  This  leaves  the  programmer  in  the  frustrating  position  of 
having  the  problem  only  when  the  cause  can’t  be  seen  and  not  having  the  problem  when 
it  can.  A  solution  to  this  type  of  problem  can  sometimes  be  found  by  moving  the  instru¬ 
mentation  outside  the  program  itself.  There  are  two  types  of  external  instrumentation: 
hardware  and  software. 
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Hardware  instrumentation  consists  of  whatever  logic  analyzers,  oscilloscopes,  metets, 
lights,  bells,  or  gongs  are  appropriate  to  the  hardware  and  software  under  test.  Hardware 
instrumentation  is  difficult  to  set  up  and  tedious  to  use.  It  is,  therefore,  usually  reserved  for 
those  problems  directly  associated  with  hardware.  Such  problems  often  arise  when  new 
software  is  being  run  on  new  hardware  and  no  one  is  quite  sure  where  the  bugs  are. 
Because  most  programmers  reading  this  book  are  developing  software  on  tried-and-true 
personal  computer  hardware  and  because  most  of  those  programmers  are  unlikely  to  have 
a  logic  analyzer  costing  several  thousand  dollars,  we  will  skip  over  the  use  of  hardware 
instrumentation  for  software  debugging.  If  a  logic  analyzer  must  be  used,  the  programmer 
should  remember  that  the  debugging  philosophy  and  techniques  discussed  in  this  article 
can  still  be  applied  effectively. 

MS-DOS  provides  a  feature  that  is  very  useful  in  building  external  instrumentation  soft¬ 
ware:  the  TSR,  or  terminate-and-stay-resident  routine.  See  PROGRAMMING  IN  THE  MS- 
DOS  ENVIRONMENT:  Customizing  ms-dos:  Terminate-and-Stay-Resident  Utilities.  This 
feature  of  the  operating  system  allows  the  programmer  to  build  a  monitoring  routine  that 
is,  in  essence,  a  part  of  the  operating  system  and  outside  the  application  program.  The  TSR 
is  loaded  as  a  normal  program,  but  instead  of  leaving  the  system  when  it  is  done,  it  remains 
intact  in  memory.  The  operating  system  provides  no  way  to  reexecute  the  program  after  it 
terminates,  so  most  TSRs  are  interrupt  driven. 

Because  TSRs  exist  outside  the  application  program,  they  can  be  used  to  build  external 
instrumentation  devices.  This  independence  allows  them  to  perform  monitoring  functions 
without  disturbing  the  logic  flow  of  the  application  program.  The  only  areas  where  inter¬ 
ference  is  likely  are  those  where  the  TSR  and  the  program  must  use  common  resources. 
These  conflicts  typically  involve  timing  but  can  also  involve  other  resources,  such  as  I/O 
devices,  disk  files,  and  MS-DOS  resources,  including  environment  space.  Some  of  these 
problems  are  addressed  in  the  next  example. 

The  TSR  type  of  external  instrumentation  software  can  prove  useful  in  analyzing  serial 
communications.  Such  an  instrumentation  program  monitors  the  serial  communication 
line  and  records  all  data.  To  detect  protocol  or  timing  problems,  the  program  tags  the 
recorded  data  so  that  transmitted  data  can  be  differentiated  from  received  data.  Hardware 
devices  exist  that  plug  into  the  serial  port  and  perform  both  the  monitoring  and  tagging 
function,  but  they  are  expensive  and  not  always  handy.  Fortunately,  this  inexpensive  piece 
of  software  instrumentation  will  serve  in  many  cases. 

Software  interrupt  calls  are  made  with  the  INT  instruction.  Although  their  service  routines 
must  obey  similar  rules,  these  interrupts  should  not  be  confused  with  hardware  interrupts 
caused  by  external  hardware  events.  Software  interrupts  in  MS-DOS  are  used  by  an  appli¬ 
cation  program  to  communicate  with  the  operating  system  and,  by  extension  in  IBM  sys¬ 
tems,  with  the  ROM  BIOS.  For  example,  on  IBM  PCs  and  compatibles,  application  pro¬ 
grams  can  use  software  Interrupt  14H  to  communicate  with  the  ROM  BIOS  serial  port 
driver.  The  ROM  BIOS  routine,  in  turn,  manages  the  hardware  interrupts  from  the  actual 
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serial  device.  Thus,  Interrupt  14H  does  not  communicate  directly  with  the  hardware.  All 
the  programs  in  this  article  deal  with  software  interrupts  to  the  ROM  BIOS  and  MS-DOS. 

A  program  to  trace  the  serial  data  flow  must  have  access  to  the  serial  data,  so  such  a  pro¬ 
gram  must  replace  the  vector  for  Interrupt  14H  with  one  that  points  to  itself  The  routine 
can  then  record  all  the  serial  data  and  pass  it  along  through  the  serial  port.  Because  the 
goal  is  to  minimize  the  effect  of  this  monitoring  on  the  timing  of  the  data,  the  method  used 
for  recording  the  data  should  be  fast.  This  requirement  rules  out  writing  to  a  disk  file, 
because  unexpected  delays  can  be  introduced  (and  because  doing  disk  I/O  from  an  inter¬ 
rupt  service  routine  under  MS-DOS  is  difficult,  if  not  impossible).  Printing  the  data  on 
paper  is  clearly  too  slow,  and  data  displayed  on  the  screen  is  too  ephemeral.  Thus,  about 
the  only  thing  that  can  be  done  with  the  data  is  to  write  it  to  RAM.  Luckily,  memory  has 
become  cheap  and  most  personal  computers  have  plenty. 

Writing  a  routine  that  monitors  and  records  serial  data  is  not  enough,  however.  The  data 
must  still  flow  through  the  serial  port  to  and  from  the  external  serial  device.  Thus,  the 
monitor  program  can  have  only  temporary  custody  of  the  data  and  must  pass  it  on  to  the 
serial  interrupt  service  routine  in  the  ROM  BIOS.  This  is  accomplished  by  using  MS-DOS 
function  calls  to  extract  the  address  of  the  serial  interrupt  handler  before  the  new  vector  is 
installed  in  its  place.  The  process  of  intercepting  interrupts  and  then  passing  the  data  on  is 
known  as  “daisy-chaining”  interrupt  handlers.  So  long  as  such  intercepting  programs  are 
careful  to  maintain  the  data  and  conditions  upon  entrance  for  subsequent  routines  (that  is, 
so  long  as  routines  are  well  behaved;  see  PROGRAMMING  IN  THE  MS-DOS  ENVIRON¬ 
MENT:  Programming  for  ms-dos),  several  interrupt  handlers  can  be  daisy-chained 
together  with  no  detriment  to  processing.  (Woe  be  unto  the  person  who  breaks  the  daisy 
chain — the  results  are  annoying  at  best  and  unpredictable  at  worst.) 

The  serial  monitoring  program,  as  described  so  far,  correctly  collects  and  stores  serial  data 
and  then  passes  it  on  to  the  serial  port.  This  may  be  intellectually  satisfying,  but  it  is  not  of 
much  use  in  the  real  world.  Some  way  must  be  provided  to  control  the  program — to  start 
collection,  to  stop  collection,  to  pause  and  resume  collection.  Also,  once  data  is  collected, 
a  control  function  must  be  provided  that  returns  the  number  of  bytes  collected  and  their 
starting  location,  so  that  the  data  can  be  examined. 

From  all  this,  it  is  clear  that  a  serial  communications  monitoring  instrument  must 

1 .  Replace  the  Interrupt  14H  vector  with  one  pointing  to  itself 

2.  Save  the  address  of  the  old  interrupt  handler. 

3.  Collect  the  serial  data,  tag  it  as  transmitted  or  received,  and  store  it  in  RAM. 

4.  Pass  the  data  on,  in  a  completely  transparent  manner,  to  the  old  interrupt  handler. 

5.  Provide  some  way  to  control  data  collection. 

A  program  that  meets  all  these  criteria  is  shown  in  Figure  18-4.  The  COMMSCOP  program 
has  three  major  parts: 
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Procedure  Purpose 

COMMSCOPE  Monitoring  and  tagging 

CONTROL  External  control 

VECTOR_  INIT  Interrupt  vector  initialization 

The  COMMSCOPE  procedure  provides  the  new  Interrupt  14H  handler  that  intercepts  the 
serial  I/O  interrupts.  The  CONTROL  procedure  provides  the  external  control  needed  to 
make  the  system  work.  The  VECTOR^INIT  procedure  gets  the  old  interrupt  handler 
address,  installs  COMMSCOPE  as  the  new  interrupt  handler,  and  installs  the  interrupt 
handler  for  the  control  interrupt. 

TITLE  COMMSCOP  —  COMMUNICATIONS  TRACE  UTILITY 


;  *  * 

;  *  COMMSCOP  —  * 

;  *  THIS  PROGRAM  MONITORS  THE  ACTIVITY  ON  A  SPECIFIED  COMM  PORT  ♦ 

;  *  AND  PLACES  A  COPY  OF  ALL  COMM  ACTIVITY  IN  A  RAM  BUFFER.  EACH  * 

;  *  ENTRY  IN  THE  BUFFER  IS  TAGGED  TO  INDICATE  WHETHER  THE  BYTE  ♦ 

;  ♦  WAS  SENT  BY  OR  RECEIVED  BY  THE  SYSTEM.  * 

;  *  * 

;  *  COMMSCOP  IS  INSTALLED  BY  ENTERING  * 

;  *  * 

;  *  COMMSCOP  * 

;  *  * 

;  *  THIS  WILL  INSTALL  COMMSCOP  AND  SET  UP  A  64K  BUFFER  TO  BE  USED  * 

;  *  FOR  DATA  LOGGING.  REMEMBER  THAT  2  BYTES  ARE  REQUIRED  FOR  * 

;  *  EACH  COMM  BYTE,  SO  THE  BUFFER  IS  ONLY  32K  EVENTS  LONG,  OR  ABOUT  * 

;  *  30  SECONDS  OF  CONTINUOUS  9600  BAUD  DATA.  IN  THE  REAL  WORLD,  * 

;  *  ASYNC  DATA  IS  RARELY  CONTINUOUS,  SO  THE  BUFFER  WILL  PROBABLY  * 

;  *  HOLD  MORE  THAN  30  SECONDS  WORTH  OF  DATA.  * 

;  ♦  * 

;  *  WHEN  INSTALLED,  COMMSCOP  INTERCEPTS  ALL  INT  1 4H  CALLS.  IF  THE  * 

;  *  PROGRAM  HAS  BEEN  ACTIVATED  AND  THE  INT  IS  EITHER  SEND  OR  RE-  * 

;  *  CEIVE  DATA,  A  COPY  OF  THE  DATA  BYTE,  PROPERLY  TAGGED,  IS  PLACED  * 

;  *  IN  THE  BUFFER.  IN  ANY  CASE,  DATA  IS  PASSED  ON  TO  THE  REAL  * 

;  *  INT  14H  HANDLER.  * 

;  ♦  * 

;  *  COMMSCOP  IS  INVOKED  BY  ISSUING  AN  INT  60H  CALL.  THE  INT  HAS  * 

;  *  THE  FOLLOWING  CALLING  SEQUENCE:  * 

;  *  * 

;  *  AH  —  COMMAND  * 

;  *  0  —  STOP  TRACING,  PLACE  STOP  MARK  IN  BUFFER  * 

;  *  1  —  FLUSH  BUFFER  AND  START  TRACE  * 

;  *  2  —  RESUME  TRACE  * 

;  *  3  —  RETURN  COMM  BUFFER  ADDRESSES  * 

;  *  DX  —  COMM  PORT  (ONLY  USED  WITH  AH  =  1  or  2)  ♦ 

;  *  0  —  COM1  * 

;  *  1  —  COM2  * 

Figure  18-4.  Communications  trace  utility.  (more) 


558  The  MS-DOS  Encyclopedia 


Article  18:  Debugging  in  the  MS-DOS  Environment 


*  * 

*  THE  FOLLOWING  DATA  IS  RETURNED  IN  RESPONSE  TO  AH  =  3 :  ♦ 

♦  * 

*  CX  —  BUFFER  COUNT  IN  BYTES  * 

*  DX  —  SEGMENT  ADDRESS  OF  THE  START  OF  THE  BUFFER  * 

*  BX  —  OFFSET  ADDRESS  OF  THE  START  OF  THE  BUFFER  * 

*  * 

*  THE  COMM  BUFFER  IS  FILLED  WITH  2-BYTE  DATA  ENTRIES  OF  THE  * 

*  FOLLOWING  FORM:  * 

*  * 

*  BYTE  0  —  CONTROL  * 

*  BIT  0  —  ON  FOR  RECEIVED  DATA,  OFF  FOR  TRANS.  * 

*  BIT  7  —  STOP  MARK  —  INDICATES  COLLECTION  WAS  * 

*  INTERRUPTED  AND  RESUMED.  * 

*  BYTE  1  —  8-BIT  DATA  * 

*  * 


CSEG  SEGMENT 

ASSUME  CS : CSEG, DS: CSEG 

ORG  10 OH  ;TO  MAKE  A  COMM  FILE 


INITIALIZE: 

JMP  VECTOR_INIT 


;JUMP  TO  THE  INITIALIZATION 
;  ROUTINE  WHICH,  TO  SAVE  SPACE, 
;  IS  IN  THE  COMM  BUFFER 


;  SYSTEM  VARIABLES 


OLD_COMM_INT 

DD 

7 

COUNT 

DW 

0 

COMMSCOPE_INT 

EQU 

60H 

STATUS 

DB 

0 

PORT 

BUFPNTR 


DB  0 

DW  VECTOR-INIT 


ADDRESS  OF  REAL  COMM  INT 
BUFFER  COUNT 
COMMSCOPE  CONTROL  INT 
PROCESSING  STATUS 
0  —  OFF 
1  —  ON 

COMM  PORT  BEING  TRACED 
NEXT  BUFFER  LOCATION 


SUBTTL  DATA  INTERRUPT  HANDLER 

PAGE 

•  :ic:ic:ic:ic:|c:ic:ic4::ic:ic4:4:4:4c:4c4c4s4:4c:tc4c4(4c:|(:ie4c:ie4(:|(4:*4:*4:***4c3|e*4c*******9|e***)i:*9ic3(c9|e9|e3(ci|t**4‘i|‘*3ii3(:3|c*4: 


♦  * 

*  COMMSCOPE  * 

*  THIS  PROCEDURE  INTERCEPTS  ALL  INT  1 4H  CALLS  AND  LOGS  THE  DATA  * 

*  IF  APPROPRIATE.  * 

*  * 


*  * 


COMMSCOPE 

PROC  NEAR 

TEST 

CS: STATUS, 1 

;ARE 

WE  ON? 

JZ 

OLD_JUMP 

;  NO, 

SIMPLY  JUMP  TO  OLD  HANDLER 

Figure  18-4.  Continued. 
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CMP 

AH, OOH 

/SKIP  SETUP  CALLS 

JE 

OLD_JUMP 

'  • 

CMP 

AH, 03H 

/SKIP  STATUS  REQUESTS 

JAE 

OLD_JUMP 

• 

CMP 

AH, 02H 

/IS  THIS  A  READ  REQUEST? 

JE 

GET_READ 

/  YES,  GO  PROCESS 

/  DATA  WRITE 

REQUEST  —  SAVE  IF  APPROPRIATE 

CMP 

DL,CS:PORT 

IS  WRITE  FOR  PORT  BEING  TRACED? 

JNE 

OLD_JUMP 

NO,  JUST  PASS  IT  THROUGH 

PUSH 

DS 

SAVE  CALLER'S  REGISTERS 

PUSH 

BX 

PUSH 

CS 

SET  UP  DS  FOR  OUR  PROGRAM 

POP 

DS 

MOV 

BX,BUFPNTR 

GET  ADDR  OF  NEXT  BUFFER  LOC 

MOV 

[BX],BYTE  PTR  0 

MARK  AS  TRANSMITTED  BYTE 

MOV 

[BX+1 ] ,AL 

SAVE  DATA  IN  BUFFER 

INC 

COUNT 

INCREMENT  BUFFER  BYTE  COUNT 

INC 

COUNT 

. 

INC 

BX 

POINT  TO  NEXT  LOCATION 

INC 

BX 

. 

MOV 

BUFPNTR, BX 

SAVE  NEW  POINTER 

JNZ 

WRITE_DONE 

ZERO  MEANS  BUFFER  HAS  WRAPPED 

MOV 

STATUS, 0 

TURN  COLLECTION  OFF 

WRITE_DONE: 

POP 

BX 

RESTORE  CALLER'S  REGISTERS 

POP 

DS 

JMP 

OLD_JUMP 

PASS  REQUEST  ON  TO  BIOS  ROUTINE 

/  PROCESS  A  : 

READ  DATA  REQUEST  AND  WRITE 

TO  BUFFER  IF  APPROPRIATE 

GET_READ : 

CMP 

DL,CS:PORT  ; 

rIS  READ  FOR  PORT  BEING  TRACED? 

JNE 

OLD_JUMP  ; 

r  NO,  JUST  PASS  IT  THROUGH 

PUSH 

DS 

SAVE  CALLER'S  REGISTERS 

PUSH 

BX 

PUSH 

CS 

SET  UP  DS  FOR  OUR  PROGRAM 

POP 

DS 

• 

PUSHF 

FAKE  INT  14H  CALL 

CLI 

. 

CALL 

OLD_COMM_INT 

PASS  REQUEST  ON  TO  BIOS 

TEST 

AH, 80H 

VALID  READ? 

JNZ 

READ-DONE 

NO,  SKIP  BUFFER  UPDATE 

Figure  18-4.  Continued. 
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MOV  BX,BUFPNTR 

MOV  [BX],BYTE  PTR  1 

MOV  [BX+1],AL 

INC  COUNT 

INC  COUNT 

INC  BX 

INC  BX 

MOV  BUFPNTR, BX 

JNZ  READ_DONE 

MOV  STATUS, 0 

READ_DONE : 

POP  BX 

POP  DS 

IRET 


;  JUMP  TO  COMM  BIOS  ROUTINE 

9 

OLD_JUMP : 

JMP  CS :  OLD_COMM_INT 

COMMSCOPE  ENDP 

SUBTTL  CONTROL  INTERRUPT  HANDLER 

PAGE 


*  ♦ 

*  CONTROL  * 

*  THIS  ROUTINE  PROCESSES  CONTROL  REQUESTS.  ♦ 

*  * 


;GET  ADDR  OF  NEXT  BUFFER  LOC 
;MARK  AS  RECEIVED  BYTE 
;SAVE  DATA  IN  BUFFER 
/INCREMENT  BUFFER  BYTE  COUNT 

/POINT  TO  NEXT  LOCATION 

/SAVE  NEW  POINTER 

/ZERO  MEANS  BUFFER  HAS  WRAPPED 

/TURN  COLLECTION  OFF 

/RESTORE  CALLER'S  REGISTERS 


CONTROL  PROC 

NEAR 

CMP 

AH, OOH 

STOP  REQUEST? 

JNE 

CNTL_START 

NO,  CHECK  START 

PUSH 

DS 

SAVE  REGISTERS 

PUSH 

BX 

. 

PUSH 

CS 

SET  DS  FOR  OUR  ROUTINE 

POP 

DS 

MOV 

STATUS, 0 

TURN  PROCESSING  OFF 

MOV 

BX, BUFPNTR 

PLACE  STOP  MARK  IN  BUFFER 

MOV 

[BX],BYTE  PTR  80H 

. 

MOV 

[BX+1],BYTE  PTR  OFFH 

INC 

BX 

INCREMENT  BUFFER  POINTER 

INC 

BX 

MOV 

BUFPNTR, BX 

INC 

COUNT 

INCREMENT  COUNT 

INC 

COUNT 

. 

POP 

BX 

RESTORE  REGISTERS 

POP 

DS 

. 

JMP 

CONTROL_DONE 

Figure  18-4.  Continued. 
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CNTL_START : 

CMP 

JNE 

MOV 

MOV 

MOV 

MOV 

JMP 

CNTL_RESUME ; 

CMP 

JNE 

CMP 

JE 

MOV 

MOV 

JMP 

CNTL_STATUS : 

CMP 

JNE 

MOV 

PUSH 

POP 

MOV 

CONTROL_DONE : 

I  RET 

CONTROL  ENDP 


AH,01H  /START  REQUEST? 

CNTL_RESUME  ;  NO,  CHECK  RESUME 

CS:PORT,DL  /SAVE  PORT  TO  TRACE 

CSrBUFPNTR, OFFSET  VECTOR_INIT  /RESET  BUFFER  TO  START 

CS : COUNT, 0  / ZERO  COUNT 

CS : STATUS, 1  /START  LOGGING 

CONTROL-DONE 


AH, 02H 

CNTL-STATUS 

CS:BUFPNTR,0 

CONTROL-DONE 

CS:PORT,DL 

CS: STATUS, 1 

CONTROL-DONE 


/RESUME  REQUEST? 

/  NO,  CHECK  STATUS 
/END  OF  BUFFER  CONDITION? 
/  YES,  DO  NOTHING 
/SAVE  PORT  TO  TRACE 
/START  LOGGING 


AH,03H 
CONTROL-DONE 
CX,CS: COUNT 
CS 
DX 

BX, OFFSET  VECTOR-INIT 


/RETURN  STATUS  REQUEST? 

/  NO,  ERROR  —  DO  NOTHING 
/RETURN  COUNT 

/RETURN  SEGMENT  ADDR  OF  BUFFER 
/RETURN  OFFSET  ADDR  OF  BUFFER 


SUBTTL  INITIALIZE  INTERRUPT  VECTORS 

PAGE 

.  4c4c*4c«4c«***********9ic**9ic*««*«****«4(4:4:*«**!ic)ic**************Hc**********!|c*** 

/  *  * 

/  *  VECTOR-INIT  * 

/  *  THIS  PROCEDURE  INITIALIZES  THE  INTERRUPT  VECTORS  AND  THEN  * 

/  *  EXITS  VIA  THE  MS-DOS  TERMINATE-AND-STAY-RESIDENT  FUNCTION.  * 

/  *  A  BUFFER  OF  64K  IS  RETAINED,  THE  FIRST  AVAILABLE  BYTE  * 

/  *  IN  THE  BUFFER  IS  THE  OFFSET  OF  VECTOR-INIT.  * 

/  *  * 

;  *:if:t::^*ili::ti*4‘********************************:ti**********'*****************iii 


EVEN  /ASSURE  BUFFER  ON  EVEN  BOUNDARY 

VECTOR-INIT  PROC  NEAR 

/  GET  ADDRESS  OF  COMM  VECTOR  (INT  1 4H) 

MOV  AH, 35H 

Figure  18-4.  Continued. 
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MOV 

AL, 14H 

INT 

21H 

SAVE  OLD  COMM  INT  ADDRESS 


MOV 

WORD  PTR  OLD_COMM_INT,BX 

MOV 

AX,ES 

MOV 

WORD  PTR  0LD_C0MM_INT[2] ,AX 

;  SET  UP  COMM 

INT  TO  POINT  TO  OUR  ROUTINE 

MOV 

DX, OFFSET  COMMSCOPE 

MOV 

AH,25H 

MOV 

AL,14H 

INT 

21H 

;  INSTALL  CONTROL  ROUTINE  INT 


MOV 

DX, OFFSET  CONTROL 

MOV 

AH,25H 

MOV 

AL,COMMSCOPE_INT 

INT 

21H 

;  SET  LENGTH 

TO  64K,  EXIT  AND  STAY  RESIDENT 

MOV 

AX,3100H 

/TERM  AND  STAY  RES  COMMAND 

MOV 

DX, 1 OOOH 

;64K  RESERVED 

INT 

21H 

;  DONE 

VECTOR_INIT  ENDP 

CSEG  ENDS 

END 

INITIALIZE 

Figure  18-4.  Continued. 

The  first  executable  statement  of  the  program  is  a  jump  to  the  VECTOR^INIT  procedure. 
The  vector  initialization  code  is  needed  only  during  installation;  after  initialization  of  the 
vectors,  the  code  can  be  discarded.  In  this  case,  the  area  where  this  code  resides  will 
become  the  start  of  the  trace  buffer;  therefore,  it  makes  sense  to  put  the  initialization  code 
at  the  end  of  the  program  where  it  can  be  overlaid  by  the  trace  buffer.  The  jump  at  the  start 
of  the  program  is  required  because  the  rules  for  making  .COM  files  require  that  the  entry 
point  be  the  first  instruction  of  the  program. 

The  vector  initialization  routine  uses  Interrupt  21H  Function  35H  (Get  Interrupt  Vector) 
to  get  the  address  of  the  current  Interrupt  14H  service  routine.  The  segment  and  offset  ad¬ 
dress  (returned  in  the  ES:BX  registers)  is  stored  in  the  doubleword  at  QZZL  COMAL,  INT. 
Interrupt  21H  Function  25H  (Set  Interrupt  Vector)  is  then  used  to  vector  all  Interrupt  14H 
calls  to  COMMSCOPE.  Another  Function  25H  call  sets  Interrupt  60H  to  vector  to  the 
CONTROL  routine.  This  interrupt,  which  provides  the  means  to  control  and  interrogate 
the  COMMSCOPE  routine,  was  chosen  because  it  is  unused  by  MS-DOS  and  because  some 
IBM  technical  materials  list  60H  through  66H  as  being  available  for  user  interrupts.  (If, 
for  some  reason.  Interrupt  60H  is  not  available,  simply  change  the  equated  symbol 
COMMSCOPE_INT  to  an  available  interrupt.) 
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When  the  vector  initialization  process  is  complete,  the  routine  exits  and  stays  resident  by 
using  Interrupt  21H  Function  31H  (Terminate  and  Stay  Resident).  As  part  of  the  termina¬ 
tion  process,  the  routine  requests  lOOOH  paragraphs,  or  64  KB,  of  storage.  A  little  over  500 
bytes  of  this  storage  area  is  used  for  the  code;  the  rest  is  available  for  trace  data.  If  the  serial 
port  is  running  at  2400  baud,  a  solid  stream  of  data  will  fill  this  buffer  in  about  two  min¬ 
utes.  However,  a  solid  32  KB  block  of  data  is  unusual  in  asynchronous  communications 
and,  in  reality,  the  buffer  will  usually  contain  many  minutes  worth  of  data.  Note  that  the 
buffer-handling  routines  in  COMMSCOPE  require  that  the  buffer  be  aligned  on  an  even 
byte  boundary,  so  VECT01L.INIT  is  preceded  by  the  EVEN  directive. 

The  interrupt  service  routine,  COMMSCOPE,  receives  all  Interrupt  14H  calls.  First 
COMMSCOPE  checks  its  own  status.  If  it  has  not  been  activated,  it  immediately  passes 
control  to  the  real  service  routine.  If  the  tracer  is  active,  COMMSCOPE  examines  the  Inter¬ 
rupt  14H  function  in  AH.  Setup  and  status  requests  (AH  =  0  and  AH  =  3)  do  not  affect  trac¬ 
ing,  so  they  are  passed  on  directly  to  the  the  real  service  routine.  If  the  Interrupt  14H  call 
is  a  write-data  request  (AH  =  1),  COMMSCOPE  moves  the  byte  marking  the  data  as  trans¬ 
mitted  and  the  data  byte  itself  to  the  current  buffer  location  and  increments  both  the  byte 
count  and  the  buffer  pointer  by  2.  If  the  buffer  pointer  goes  to  zero,  the  buffer  has 
wrapped;  data  collection  is  turned  off  and  cannot  be  turned  on  again  without  clearing  the 
trace  buffer.  Because  the  buffer,  which  starts  at  VECTOR_INIT,  is  always  on  an  even  byte 
boundary,  there  is  no  danger  of  the  first  byte  of  the  data  pair  forcing  a  wrap.  After  the 
transmitted  data  is  added  to  the  buffer,  COMMSCOPE  passes  control  to  the  real  service 
routine. 

A  read-data  request  (AH  =  2)  must  be  handled  a  little  differently.  In  this  case,  the  data 
to  be  collected  is  not  yet  available.  In  order  to  get  it,  COMMSCOPE  must  pass  control  to 
the  real  service  routine  and  then  intercept  the  results  on  the  way  back.  The  code  at 
GET_READ  fakes  an  interrupt  to  the  service  routine  by  pushing  the  flags  onto  the  stack  so 
that  the  service  routine’s  IRET  will  pop  them  off  again.  COMMSCOPE  then  calls  the  ser¬ 
vice  routine  and,  when  it  returns,  retrieves  the  incoming  serial  data  character  from  AL.  If 
the  incoming  data  byte  is  valid  (bit  7  of  AH  is  zero),  the  byte  marking  the  data  as  received 
and  the  data  byte  itself  are  placed  in  the  trace  buffer,  and  both  the  byte  count  and  the 
buffer  pointer  are  incremented  by  2.  The  buffer-wrap  condition  is  detected  and  handled  in 
the  same  manner  as  with  transmitted  data.  Because  the  real  service  routine  has  already 
been  called,  COMMSCOPE  exits  as  if  it  were  the  service  routine  by  issuing  an  IRET. 

The  CONTROL  procedure  provides  the  mechanism  for  external  control  of  the  trace  pro¬ 
cedure.  The  routine  is  entered  whenever  an  Interrupt  60H  is  executed.  Commands  are 
sent  through  the  AH  register  and  can  cause  the  routine  to  STOP  (AH  =  0),  START/FLUSH 
(AH  =  1),  RESUME  (AH  =  2),  or  RETURN  STATUS  (AH  =  3).  This  routine  also  sets  the  com¬ 
munications  port  to  be  traced.  The  required  information  is  provided  in  DX  using  the  same 
format  as  the  Interrupt  14H  routine.  The  port  information  is  used  only  with  START  and 
RESUME  requests.  The  RETURN  STATUS  command  returns  data  in  registers:  the  byte 
count  (CX),  the  segment  address  of  the  buffer  (DX),  and  the  offset  of  the  first  byte  in  the 
buffer  (BX). 
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The  COMMSCOP  program  is  assembled  using  the  Microsoft  Macro  Assembler  (MASM), 
linked  using  the  Microsoft  Object  Linker  (LINK),  and  then  converted  to  a  .COM  file  using 
EXE2BIN  (see  PROGRAMMING  UTILITIES): 

C>MASM  COMMSCOP;  <Enter> 

C>LINK  COMMSCOP;  <Enter> 

C>EXE2BIN  COMMSCOP.EXE  COMMSCOP.COM  <Enter> 

C>DEL  COMMSCOP.EXE  <Enter> 

The  linker  will  display  the  message  Warning:  no  stack  segment-,  this  message  can  be 
ignored  because  the  rules  for  making  a  .COM  file  forbid  a  separate  stack  segment. 

The  program  is  installed  by  simply  typing  COMMSCOP,  Tracing  can  then  be  started  and 
stopped  using  Interrupt  60H.  MS-DOS  does  not  allow  resident  routines  to  be  removed,  so 
COMMSCOP  will  be  in  the  system  until  the  system  is  restarted.  Also  note  that,  because 
COMMSCOP  is  well  behaved,  nothing  disastrous  will  happen  if  multiple  copies  of  it  are 
accidentally  installed.  As  each  new  copy  is  installed,  it  chains  to  the  previous  copy.  When 
Interrupt  14H  is  intercepted,  the  new  routine  dutifully  passes  the  data  on  to  the  previous 
routine,  which  repeats  the  process  imtil  the  real  service  routine  is  reached.  The  data  is 
added  to  the  trace  buffer  of  each  copy,  giving  multiple,  redundant  copies  of  the  same  data. 
Because  Interrupt  60H  is  not  chained,  only  the  last  copy’s  buffer  can  be  accessed.  Thus, 
the  other  copies  simply  waste  64  KB  each. 

Two  techniques  can  be  used  to  start  or  stop  a  trace.  The  first  is  to  issue  Interrupt  60H 
calls  at  strategic  locations  within  the  program  being  debugged.  With  assembly-language 
programs,  this  is  easy.  The  appropriate  registers  are  loaded  and  an  INT  60H  instruction  is 
executed.  Issuing  this  INT  instruction  is  not  much  more  difficult  with  higher-order  Micro¬ 
soft  languages — both  QuickBASIC  and  C  provide  a  library  routine  called  INT86  that 
allows  registers  to  be  loaded  and  INT  instructions  to  be  executed.  (In  QuickBASIC,  the 
INT86  library  routine  is  included  in  the  File  USERLIB.OBJ;  in  Microsoft  C,  it  is  included  in 
the  file  DOS.H.)  Embedded  Interrupt  60H  calls  can  be  convenient  because  they  limit  trac¬ 
ing  to  those  areas  where  processing  is  suspect.  Because  COMMSCOP  marks  the  buffer 
each  time  the  trace  is  stopped  and  resumed,  the  separate  pieces  of  a  trace  are  easy  to  dif¬ 
ferentiate. 

The  second  technique  is  to  write  a  simple  routine  to  start  or  stop  the  trace  outside  the  pro¬ 
gram  being  debugged.  The  example  in  Figure  18-5,  COMMSCMD,  is  a  Microsoft  C  program 
that  can  perform  these  functions  using  the  INT86  library  function  to  issue  Interrupt  60H 
calls. 


/ 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 


* 

COMMSCMD  * 

* 

This  routine  controls  the  COMMSCOP  program  that  has  been  in-  * 

stalled  as  a  resident  routine.  The  operation  performed  is  de-  * 

termined  by  the  command  line.  The  COMMSCMD  program  is  invoked  * 

as  follows:  * 

* 

COMMSCMD  [[cmd][  port]]  * 

* 


Figure  18-5.  A  serial-trace  control  routine  written  in  C. 
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*  where  cmd  is  the  corranand  to  be  executed  * 

*  STOP  —  stop  trace  * 

*  START  —  flush  trace  buffer  and  start  trace  * 

*  RESUME  —  resume  a  stopped  trace  * 

*  port  is  the  COMM  port  to  be  traced  (1=C0M1,  2=COM2,  etc.)  * 

*  * 

*  If  cmd  is  omitted,  STOP  is  assumed.  If  port  is  omitted,  1  is  * 

*  assumed.  * 

*  * 


#include  <stdlib.h> 

#include  <stdio.h> 

#include  <dos.h> 

#define  COMMCMD  0x60 

main(argc,  argv) 
int  argc; 
char  *argv[]; 

{ 

int  cmd,  port,  result; 

static  char  commands [3]  [10]  =  {"STOPPED”,  "STARTED",  "RESUMED"}; 

union  REGS  inregs,  outregs; 

cmd  =  0; 
port  =  0; 

if  (argc  >  1 ) 

{ 

if  (0  ==  stricmp(argv[1] ,  "STOP")) 
cmd  =  0; 

else  if  (0  ==  stricmp (argv [ 1 ] ,  "START")) 
cmd  =  1 ; 

else  if  (0  ==  stricmp (argv [ 1 ] ,  "RESUME")) 
cmd  =2; 


if  (argc  ==  3) 

{ 

port  =  atoi (argv [2] ) ; 
if  (port  >  0) 

port  =  port  -  1 ; 

} 


inregs. h. ah  =  cmd; 
inregs. x.dx  =  port; 

result  =  intS 6 (COMMCMD,  Sinregs,  &outregs) ; 


} 


printf ("\nCommunications  tracing  %s  for  port  COM%1d:\n", 
commands [cmd] ,  port  +  1); 


Figure  18-5.  Continued. 
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COMMSCMD  is  passed  arguments  in  the  command  line.  The  first  argument  is  the  com¬ 
mand  to  be  performed:  STOP,  START,  or  RESUME.  If  no  command  is  specified,  STOP  is 
assumed.  The  second  argument  is  the  port  number:  1  (for  COMl)  or  2  (for  COM2).  If  no 
port  number  is  specified,  1  is  assumed. 

The  COMMSCMD  program  uses  a  simple  IF  filter  to  determine  the  function  to  be  per¬ 
formed.  The  program  tests  the  number  of  arguments  in  the  command  line  to  see  if  a  port 
has  been  specified.  If  the  argument  count  (.argd  is  3  (one  for  the  command  name,  one  for 
the  command,  and  one  for  the  port  number),  the  port  number  argument  is  retrieved  and 
converted  to  an  integer.  The  Interrupt  60H  routine  expects  port  numbers  to  be  specified  in 
the  same  manner  as  for  Interrupt  14H,  so  the  port  number  is  decremented  if  it  is  not  already 
zero.  The  AH  register  is  loaded  with  the  command  icmd),  the  DX  register  is  loaded  with 
the  port  number  (port),  and  the  INT86  library  function  is  then  used  to  execute  an  Interrupt 
60H  call.  When  the  interrupt  returns,  COMMSCMD  displays  a  message  showing  the  func¬ 
tion  and  port. 

The  same  function  can  be  performed  by  the  QuickBASIC  program  in  Figure  18-6. 


*  * 

*  COMMSCMD  * 

*  * 

*  This  routine  controls  the  COMMSCOP  program  that  has  been  in-  * 

*  stalled  as  a  resident  routine.  The  operation  performed  is  de-  * 

*  termined  by  the  command  line.  The  COMMSCMD  program  is  invoked  * 

*  as  follows:  * 

*  * 

*  COMMSCMD  [ [cmd] [,port] ]  * 

*  * 

*  where  cmd  is  the  command  to  be  executed  * 

*  STOP  —  stop  trace  * 

*  START  —  flush  trace  buffer  and  start  trace  * 

*  RESUME  —  resume  a  stopped  trace  * 

*  port  is  the  COMM  port  to  be  traced  {1=C0M1,  2=COM2,  etc.)  * 

*  * 

*  If  cmd  is  omitted,  STOP  is  assumed.  If  port  is  omitted,  1  is  * 

*  assumed.  * 

*  * 


'  Establish  system  constants  and  variables 

I 

DEFINT  A-Z 

DIM  INREG{7),  0UTREG(7)  ’Define  register  arrays 

Figure  18-6.  A  QuickBASIC  version  of  COMMSCMD.  (more) 
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RAX  =  0 

'Establish  values 

RBX  =  1 

'  registers 

RCX  =  2 

t 

RDX  =  3 

1 

RBP  =  4 

1 

RSI  =  5 

t 

RDI  =  6 

1 

RFL  =  7 

1 

DIM  TEXT$(2) 

TEXT${0)  =  "STOPPED" 

TEXT$(1)  =  "STARTED" 

TEXT${2)  =  "RESUMED" 

'  Process  command- line  tail 

I 

C$  =  COMMAND $ 

IF  LEN(C$)  =  0  THEN 
CMD  =  0 
PORT  =  0 
GOTO  SENDCMD 
END  IF 

COMMA  =  INSTR(C$,  ",  ") 

IF  COMMA  =  0  THEN 
CMDTXT$  =  C$ 

PORT  =  0 

ELSE 

CMDTXT$  =  LEFT$(C$,  COMMA 
PORT  =  VAL(MID$(C$,  COMMA 
END  IF 


'Get  command-line  data 

'If  no  command  line  specified 
'Set  CMD  to  STOP 
'Set  PORT  to  C0M1 


'Extract  operands 


1) 

D)  -  1 


IF  PORT  <  0  THEN  PORT  =  0 

IF  CMDTXT$  =  "STOP"  THEN 
CMD  =  0 

ELSEIF  CMDTXT$  =  "START"  THEN 
CMD  =  1 

ELSEIF  CMDTXT$  =  "RESUME"  THEN 
CMD  =  2 

ELSE 

CMD  =  0 
END  IF 


'  Send  command  to  COMMSCOP  routine 

I 

SENDCMD : 

INREG(RAX)  =  256  *  CMD 

Figure  18-6.  Continued. 
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INREG(RDX)  =  PORT 

CALL  INT86(&H60,  VARPTR (INREG (0) ) ,  VARPTR (OUTREG ( 0 ) ) ) 

'  Notify  user  that  action  is  complete 

f 

PRINT  :  PRINT 

PRINT  "Communications  tracing  TEXT$ (CMD) ; 

IF  CMD  <>  0  THEN 

PRINT  "  for  port  COM";  MID$ (STR$ (PORT  +1),  2);  ":" 

ELSE 

PRINT 
END  IF 

END 

Figure  18-6.  Continued. 

Both  versions  of  COMMSCMD  accept  their  commands  from  the  command  tail;  both  are 
invoked  with  a  STOP,  START,  or  RESUME  command  and  a  serial  port  number  (1  or  2).  If 
the  operands  are  omitted,  STOP  and  COMl  are  assumed. 

After  data  has  been  collected  and  safely  placed  in  the  trace  buffer,  it  must  be  read  before 
it  can  be  useful.  Interrupt  60H  provides  a  function  (AH  =  3)  that  returns  the  buffer  address 
and  the  number  of  bytes  in  the  buffer.  The  QuickBASIC  routine  in  Figure  18-7  uses  this 
function  to  get  the  address  of  the  data  and  then  formats  the  data  on  the  screen. 

»  :((  * 

•  *  COMMDUMP  * 

I  *  ♦ 

'  *  This  routine  dumps  the  contents  of  the  COMMSCOP  trace  buffer  to  * 

'  *  the  screen  in  a  formatted  manner.  Received  data  is  shown  in  * 

'  *  reverse  video.  Where  possible,  the  ASCII  character  for  the  byte  * 

'  *  is  shown;  otherwise  a  dot  is  shown.  The  value  of  the  byte  is  * 

'  *  displayed  in  hex  below  the  character.  Points  where  tracing  was  * 

'  *  stopped  are  shown  by  a  solid  bar.  * 

»  *  * 

>  **Hi*******4c**3i:*****************************  ********4:*****  !ic*  *********** 


Establish  system  constants  and  variables 


DEFINT  A-Z 

DIM  INREG (7),  OUTREG (7)  'Define  register  arrays 

RAX  =  0  'Establish  values  for  8086 

RBX  =  1  '  registers 

RCX  =2  '  . 

RDX  =3  '  . 

Figure  18-  7.  Formatted  dump  routine  for  serial-trace  buffer.  (more) 
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RBP  =  4 
RSI  =  5 
RDI  =  6 
RFL  =  7 


'  Interrogate  COMMSCOP  to  obtain  addresses  and  count  of  data  in 
'  trace  buffer 

I 

INREG(RAX)  =  &H0300  'Request  address  data  and  count 

CALL  INT86(&H60,  VARPTR(INREG (0) ) ,  VARPTR (OUTREG (0) ) ) 

NUM  =  OUTREG (RCX)  'Number  of  bytes  in  buffer 

BUFSEG  =  OUTREG (RDX)  'Buffer  segment  address 

BUFOFF  =  OUTREG (RBX)  'Offset  of  buffer  start 

IF  NUM  =  0  THEN  END 


'  Set  screen  up  and  display  control  data 


CLS 

KEY  OFF 
LOCATE  25,  1 

PRINT  "NUM  NUM; "BUFSEG  =  HEX$ (BUFSEG) ;  "  BUFOFF  = 
PRINT  HEX$ (BUFOFF) ; 

LOCATE  4,  1 

PRINT  STRING$ (80, "-") 

DEF  SEG  =  BUFSEG 


'  Set  up  display  control  variables 

I 

DLINE  =  1 
DCOL  =  1 
DSHOWN  =  0 


'  Fetch  and  display  each  character  in  buffer 

FOR  1=  BUFOFF  TO  BUFOFF+NUM-2  STEP  2 
STAT  =  PEEK(I) 

DAT  =  PEEK (I  +  1) 

IF  (STAT  AND  1)  =  0  THEN 
COLOR  7,  0 

ELSE 

COLOR  0,  7 
END  IF 

RLINE  =  (DLINE-1 )  *  4  +  1 

Figure  18-7.  Continued. 
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IF  (STAT  AND  &H80)  =  0  THEN 
LOCATE  RLINE,  DCOL 
C$  =  CHR$ (DAT) 

IF  DAT  <  32  THEN  C$  = 

PRINT  C$; 

H$  =  RIGHT$("00".  +  HEX$(DAT),  2) 
LOCATE  RLINE  +  1,  DCOL 
PRINT  LEFT$(H$,  1); 

LOCATE  RLINE  +  2,  DCOL 
PRINT  RIGHT$(H$,  1); 

ELSE 

LOCATE  RLINE,  DCOL 
PRINT  CHR${178); 

LOCATE  RLINE.  +  1,  DCOL 
PRINT  CHR$(178); 

LOCATE  RLINE  +  2,  DCOL 
PRINT  CHR$(178); 

END  IF 

DCOL  =  DCOL  +  1 
IF  DCOL  >80  THEN 
COLOR  7,  0 
DCOL  =  1 

DLINE  =  DLINE  +  1 
SHOWN  =  SHOWN  +  1 
IF  SHOWN  =  6  THEN 
LOCATE  25,  50 
COLOR  0,  7 

PRINT  "ENTER  ANY  KEY  TO  CONTINUE: 

WHILE  LEN(INKEY$)  =  0 

WEND 

COLOR  7,  0 
LOCATE  25,  50 
PRINT  SPACE$(29); 

SHOWN  =  0 
END  IF 

IF  DLINE  >  6  THEN 
LOCATE  24,  1 

PRINT  :  PRINT  :  PRINT  :  PRINT 

LOCATE  24,  1 

PRINT  STRING$(80,  ; 

DLINE  =  6 

ELSE 

LOCATE  DLINE  *  4,  1 
PRINT  STRING$(80,  ; 

END  IF 
END  IF 

NEXT  I 

END 

Figure  18-7.  Continued. 
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COMMDUMP  is  a  simple  routine.  Like  most  debugging  aids,  it  lacks  needless  frills.  When 
it  is  executed,  COMMDUMP  displays  the  data  in  the  trace  buffer  on  the  screen  in  the  for¬ 
mat  shown  in  Figure  18-8. 


. 012832 . 132056780001806713205678000100671320567800010067132056780001006713205678 
B3333330333333333333333333333333333333333333333333333333333333333333333333333333 
10128323132056780001006713205678000100671320567800010067132056780001006713205678 

00010067132056780001006713205678000100671320567800010067 .» .1 
333333333333333333333333333333333333333333333333333333330213 
000100671320567800010067132056780001006713205678000108673381 

.012832.567813200001 

03333330333333333333 

10128323567813200001 

00675678132000010067567813200001006756781320000100675678132800010067567813200001 

33333333333333333333333333333333333333333333333333333333333333333333333333333333 

00675678132000010067567813200001006756781320800100675678132000010867567813200001 

006756781320080100675678132000010067 .« .1 
333333333333333333333333333333333333021] 
006756781320000100675678132000010067338] 

.812832.00671320567800010067132056780001 

0333333033333333333333333333333333333333 

1012832300671320567800010067132056780081 

00671320567800010067132056780001006713205678080100671320567800010067132056780001 

33333333333333333333333333333333333333333333333333333333333333333333333333333333 

00671320567800010067132056780001006713205678000100671320567800010067132856780001 

0067132056780001.  It.  1 
3333333333333333021] 
0067132056780001338] 

.012832 . 1320567880018067132056780001806713205678000100671320 
033333303333333333333333333333333333333333333333333333333333 
101283231320567800010067132056780001006713205678000100671320 

HUM  =  1122  BUFSEG  =  1313  BUFOFF  =  208 


NTER  ANV  KEV  TO  CONTINUE: 


Figure  18~8.  Formatted  trace  dump  routine  output. 


Note  that  the  data  for  each  byte  is  presented  in  two  forms.  If  the  byte  is  greater  than 
IFH,  the  ASCII  character  represented  by  that  number  is  shown;  otherwise,  a  dot  is  shown. 
Directly  below  each  character  is  the  hexadecimal  representation  of  the  data.  The  display 
shows  received  data  in  reverse  video  and  transmitted  data  in  normal  video.  The  mark 
placed  in  the  buffer  when  collection  is  stopped  and  resumed  is  represented  on  the  screen 
as  a  vertical  bar  one  character  wide.  The  display  pauses  when  the  screen  is  full  and  waits 
for  a  key  to  be  pressed. 

Data  collected  and  displayed  in  this  way  can  be  invaluable  to  the  programmer  trying  to 
debug  a  program  involving  a  communications  protocol.  The  example  shown  above  is 
part  of  an  ordered  exchange  of  sales  data  for  a  system  using  blocked  transmissions  and 
ACK/NAK  protocol.  Like  all  debugging,  finding  bugs  in  such  a  system  requires  the  collec¬ 
tion  of  large  amounts  of  data.  With  no  data,  the  causes  of  problems  can  be  almost  impos¬ 
sible  to  find;  with  sufficiently  large  amounts  of  data,  the  solutions  are  obvious. 

Several  things  could  be  done  to  the  COMMSCOP  program  to  increase  its  usefulness.  For 
instance,  there  are  six  unused  bits  in  the  tag  accompanying  each  data  byte  in  the  trace 
buffer.  These  could  be  used  to  record  the  status  of  the  modem  control  bits,  to  place  timer 
ticks  in  the  buffer,  or  to  coordinate  the  data  with  some  outside  event.  (Such  changes  to 
COMMSCOP  would  require  a  more  complicated  COMMDUMP  routine  to  display  them.) 
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Software  debugging  monitors 

Debugging  monitors  provide  the  next  level  of  sophistication  in  the  hierarchy  of  debugging 
methods.  These  monitors  are  coresident  in  memory  with  the  application  being  debugged 
and  provide  a  controlled  testing  environment — that  is,  they  allow  the  programmer  to  con¬ 
trol  the  execution  of  the  program  and  to  monitor  the  results.  They  even  allow  some  prob¬ 
lems  to  be  fixed  directly  and  the  result  reexecuted  immediately,  without  the  need  to 
reassemble  or  recompile. 

These  monitors  are  analogous  to  the  TSR  serial  monitor  from  the  previous  section.  The 
debugging  monitors,  however,  do  not  reside  permanently  in  memory  and  are  controlled 
interactively  from  the  keyboard  during  the  execution  of  the  program  under  test.  Although 
this  level  of  control  is  more  flexible  than  instrumentation,  it  is  also  more  intrusive  into  pro¬ 
gram  execution.  While  the  debugging  monitor  sits  and  waits  for  input  from  the  keyboard, 
the  application  program  is  also  idle.  For  programs  that  must  run  in  real  time  or  must 
respond  to  external  stimuli,  long  delays  can  be  fatal.  Careful  planning  and  a  thorough 
knowledge  of  the  internal  workings  of  the  program  are  required  to  debug  in  such  an 
environment. 

Other  problems  with  debugging  monitors  arise  from  the  nature  of  the  monitors  them¬ 
selves.  They  are  programs,  no  different  from  the  application  program  being  debugged  and 
are  therefore  limited  to  those  things  that  can  be  done  with  software.  For  instance,  they  can 
break  (stop  execution  to  allow  investigation  of  program  status)  when  a  specific  instruction 
address  is  executed  (because  this  can  be  done  with  software),  but  they  cannot  break 
when  a  data  address  is  referenced  (because  this  would  require  special  hardware).  Because 
these  monitors  reside  in  RAM,  as  do  the  application  program  and  MS-DOS,  they  are  sus¬ 
ceptible  to  damage  from  a  program  running  wild.  Some  trial  and  error  is  usually  involved 
in  locating  the  problem  causing  this  kind  of  damage;  breakpoints  won't  work  here  because 
the  problem  kills  the  monitor  (and  usually  MS-DOS  also). 

Microsoft  provides  three  debugging  monitors,  each  with  greater  capabilities  than  its  pre¬ 
decessor.  In  order  of  increasing  sophistication,  these  three  monitors  are 


Monitor  Description 


DEBUG 

SYMDEB 


CodeView 


A  basic  debugging  monitor  with  the  ability  to  load  files,  modify  memory 
and  registers,  execute  programs,  set  simple  breakpoints,  trace  execution, 
modify  disk  files,  and  enter  assembly-language  statements  into  memory. 

A  more  advanced  debugging  monitor  incorporating  all  the  features  of 
DEBUG  plus  more  sophisticated  data  display,  support  for  graphics  pro¬ 
grams,  support  for  the  Intel  80186/80286  microprocessors  and  the  Intel 
80287  math  coprocessor,  improved  breakpoints,  improved  tracing, 
recognition  of  symbols  from  the  program  being  debugged,  and  limited 
source-line  display. 

The  most  sophisticated  debugging  monitor,  incorporating  the  func¬ 
tionality  of  SYMDEB  (with  some  differences  in  the  details)  plus  win¬ 
dows,  full  source-line  support,  mouse  support,  and  generally  more 
sophistication  on  all  functions. 
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Although  all  these  debugging  monitors  will  be  discussed  here,  this  section  is  not  intended 
to  be  a  tutorial  on  all  the  commands  and  options  of  the  monitors — those  are  presented 
elsewhere  in  this  volume  and  in  the  manuals  accompanying  the  monitors.  See  PROGRAM¬ 
MING  UTILITIES:  debug;  symdeb;  CodeView.  Rather,  this  section  uses  case  histories  and 
sample  programs  to  illustrate  the  techniques  for  solving  various  types  of  common  debug¬ 
ging  problems.  The  case  histories  have  been  chosen  to  show  a  wide  range  of  problems, 
from  simple  to  extremely  complex. 

DEBUG 

Although  DEBUG  is  the  least  sophisticated  of  the  software  debugging  monitors,  it  is  quite 
useful  with  moderately  complex  programs  and  is  an  effective  tool  for  learning  basic 
techniques. 

Basic  techniques 

The  first  sample  program  is  written  in  assembly  language.  It  is  a  test  program  that  per¬ 
forms  serial  input  and  output  and  was  used  to  debug  COMMSCOP,  the  serial-trace  TSR 
presented  earlier.  The  routine  reads  from  the  keyboard  and  writes  to  COMl  by  means  of 
Interrupt  14H.  It  also  accepts  incoming  serial  data  and  displays  it  on  the  screen.  This 
process  continues  until  Ctrl-C  is  pressed  on  the  keyboard.  A  serial  terminal  is  attached 
to  COMl  to  serve  as  a  data  source.  Figure  18-9  shows  the  erroneous  program. 


TITLE  TESTCOMM  -  TEST  COMMSCOP  ROUTINE 

*  * 

*  TESTCOMM  * 

*  THIS  ROUTINE  PROVIDES  DATA  FOR  THE  COMMSCOP  ROUTINE.  IT  READS  * 

*  CHARACTERS  FROM  THE  KEYBOARD  AND  WRITES  THEM  TO  COMl  USING  * 

*  INT  14H.  DATA  IS  ALSO  READ  FROM  INT  1 4H  AND  DISPLAYED  ON  THE  * 

*  SCREEN.  THE  ROUTINE  RETURNS  TO  MS-DOS  WHEN  Ctrl-C  IS  PRESSED  * 

*  ON  THE  KEYBOARD.  * 

*  * 


SSEG  SEGMENT  PARA  STACK  'STACK* 

DW  128  DUP(?) 

SSEG  ENDS 

CSEG  SEGMENT 

ASSUME  CS : CSEG, SS: SSEG 
BEGIN  PROC  FAR 

PUSH  DS 

XOR  AX, AX 

PUSH  AX 


;SET  UP  FOR  RET  TO  MS-DOS 


Figure  18-9.  Incorrect  serial  test  routine. 
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MAINLOOP : 

MOV 

MOV 

INT 

JZ 


AH,  6 
DL,0FFH 
21 

TESTCOMM 


;USE  MS-DOS  CALL  TO  CHECK  FOR 
;  KEYBOARD  ACTIVITY 
;  IF  NO  CHARACTER,  JUMP  TO 
;  COMM  ACTIVITY  TEST 


CMP 

JNE 

RET 


AL,  03 
SENDCOMM 


;WAS  CHARACTER  A  Ctrl-C? 

;  NO,  SEND  IT  TO  SERIAL  PORT 
;  YES,  RETURN  TO  MS-DOS 


SENDCOMM: 


MOV 

AH,  01 

USE  INT  14H  WRITE  FUNCTION 

MOV 

DX,  0 

SEND  DATA  TO  SERIAL  PORT 

INT 

14H 

• 

TESTCOMM: 

MOV 

AH,  3 

GET  SERIAL  PORT  STATUS 

MOV 

DX,  0 

. 

INT 

14H 

. 

AND 

AH,  1 

ANY  DATA  WAITING? 

JZ 

MAINLOOP 

NO,  GO  BACK  TO  KEYBOARD  TE 

MOV 

AH,  2 

READ  SERIAL  DATA 

MOV 

DX,0 

. 

INT 

14H 

MOV 

AH,  6 

WRITE  SERIAL  DATA  TO  SCREEN 

INT 

21H 

JMP 

MAINLOOP 

CONTINUE 

BEGIN 

ENDP 

CSEG 

ENDS 

END 

BEGIN 

Figure  18-9.  Continued. 

When  executed,  this  program  produces  a  constant  stream  of  zeros  from  the  serial  port. 
Incoming  serial  data  is  not  echoed  on  the  screen,  but  the  cursor  moves  as  if  it  were.  Fur¬ 
ther,  the  Ctrl-C  keystroke  is  not  recognized,  so  the  only  way  to  stop  the  program  is  to 
restart  the  system. 

An  examination  of  the  listing  should  reveal  the  errors  that  cause  these  problems,  but 
things  do  not  always  happen  that  way.  For  the  purposes  of  this  case  study,  assume  that  the 
listing  was  no  help.  Instrumentation  is  more  difficult  for  assembly-language  programs  than 
for  programs  written  in  higher-order  languages,  so  in  this  case  it  is  advantageous  to  go 
directly  to  a  debugging  monitor.  The  monitor  for  this  example  is  DEBUG. 

The  first  step  in  using  DEBUG  is  not  to  invoke  the  monitor;  rather,  it  is  to  gather  all  perti¬ 
nent  listings,  link  maps,  and  program  design  documentation.  In  this  case,  the  program  is 
so  short  that  a  link  map  will  not  be  needed;  all  the  design  documentation  that  exists  is  in 
the  program  comments. 

Now  begin  DEBUG  by  typing 

C>DEBUG  TESTCOMM.EXE  <Enter> 
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The  filename  must  be  fully  qualified;  DEBUG  makes  no  assumptions  about  the  extension. 
Any  type  of  file  can  be  examined  with  DEBUG,  but  only  files  with  an  extension  of  .COM, 
.EXE,  or  .HEX  are  actually  loaded  and  made  ready  for  execution.  Since  TESTCOMM  is  a 
.EXE  file,  DEBUG  loads  it  and  prepares  it  for  execution  in  a  manner  compatible  with  the 
MS-DOS  loader.  Type  the  Display  or  Modify  Registers  command,  R. 

-R  <Enter> 

AX=0000  BX=0000  CX=0131  DX=0000  SP=0100  BP=0000  SI=0000  DI=0000 

DS=1AAD  ES=1AAD  SS=1ABD  CS=1ACD  IP=0000  NV  UP  El  PL  NZ  NA  PO  NC 

lACDiOOOO  IE  PUSH  DS 

Notice  that  the  SS  and  CS  registers  have  been  loaded  to  their  correct  values  and  that  SP 
points  to  the  bottom  of  the  stack.  DS  and  ES  point  to  an  address  lOOH  bytes  (lOH  para¬ 
graphs)  before  the  stack  segment.  (This  is  because  the  system  sets  these  registers  to  point 
to  the  program  segment  prefix  [PSP]  when  a  .EXE  program  is  loaded.)  Normally,  the  pro¬ 
gram  code  would  be  responsible  for  loading  the  correct  value  of  DS,  but  this  example  does 
not  use  the  data  segment,  so  the  program  doesn’t  bother.  The  register  display  also  shows 
the  instruction  at  the  current  value  of  CS:IP,  lACDiOOOOH.  The  instruction  pointer  was  set 
to  this  address  because  the  END  statement  in  the  source  program  specified  the  procedure 
BEGIN  as  the  entry  point  and  that  procedure  begins  at  CS:IP.  Note  that  the  instruction  dis¬ 
played  below  the  register  information  has  not  yet  been  executed.  This  condition  is  true  for 
all  register  displays  in  DEBUG — IP  always  points  to  the  next  instruction  to  be  executed, 
so  the  instruction  at  IP  has  not  been  executed. 

From  the  symptoms  observed  during  program  execution,  it  is  clear  that  the  keyboard  data 
is  not  reaching  the  serial  port.  The  failure  could  be  in  the  keyboard  read  routine  or  in  the 
serial  port  write  routine.  This  code  is  compact  and  fairly  linear,  so  the  easiest  way  to  find 
out  what  is  going  on  is  to  trace  through  the  first  few  instructions  of  the  program.  Executing 
five  instructions  with  the  Trace  Program  Execution  command,  T,  will  do  this. 

-T5  <Enter> 


AX=0000 

BX=0000 

CX=0131 

DX=0000 

SP=00FE 

BP=0000 

SI=0000 

DI=0000 

DS=1AAD  ES=1AAD 

1ACD:0001  33C0 

SS=1ABD  CS=1ACD 

XOR  AX, AX 

IP=0001 

NV  UP  El 

PL  NZ  NA  PO  NC 

AX=0000 

BX=0000 

CX=0131 

DX=0000 

SP=00FE 

BP=0000 

SI=0000 

DI=0000 

DS=1AAD  ES=1AAD 

1ACD:0003  50 

SS=1ABD  CS=1ACD 

PUSH  AX 

IP=0003 

NV  UP  El 

PL  ZR  NA  PE  NC 

AX=0000 

BX=0000 

CX=0131 

DX=0000 

SP=00FC 

BP=0000 

SI=0000 

DI=0000 

DS=1AAD  ES=1AAD 

1ACD:0004  B406 

SS=1ABD  CS=1ACD 

MOV  AH, 06 

IP=0004 

NV  UP  El 

PL  ZR  NA  PE  NC 

AX=0600 

BX=0000 

CX=0131 

DX=0000 

SP=00FC 

BP=0000 

SI=0000 

DI=0000 

DS=1AAD  ES=1AAD 

1ACD:0006  B2FF 

SS=1ABD  CS=1ACD 

MOV  DL,FF 

IP=0006 

NV  UP  El 

PL  ZR  NA  PE  NC 

AX=0600 

BX=0000 

CX=0131 

DX=00FF 

SP=00FC 

BP=0000 

SI=0000 

DI=0000 

DS=1AAD  ES=1AAD 

1ACD:0008  CD15 

SS=1ABD  CS=1ACD 

INT  15 

IP=0008 

NV  UP  El 

PL  ZR  NA  PE  NC 
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The  Trace  command  shows  the  contents  of  the  registers  as  each  instruction  is  executed. 
The  register  contents  are  after  the  execution  of  the  instruction  listed  above  the  registers 
and  the  instruction  shown  with  the  registers  is  the  next  instruction  to  be  executed.  The 
first  register  display  in  this  example  represents  the  state  of  affairs  after  the  execution  of  the 
PUSH  DS  instruction,  as  indicated  by  SP.  The  first  three  instructions  set  up  the  stack  so 
that  the  far  return  issued  at  the  end  of  the  program  will  pass  control  to  the  PSP  for  termina¬ 
tion.  The  next  two  instructions  set  the  registers  for  a  Direct  Console  I/O  MS-DOS  call 
(AH  =  060,  DL  =  HFFH  for  input).  After  these  registers  are  set  up,  the  program  should  ex¬ 
ecute  the  MS-DOS  call  INT  21H.  However,  the  next  instruction  to  be  executed  is  INT 15H. 
This  is  the  reason  the  keyboard  data  is  not  being  read.  The  code  requests  INT  21,  not  21H. 
This  mistake  is  a  common  one.  The  assembler’s  default  radix  is  decimal,  so  it  converted  21 
into  15H.  This  error  can  be  corrected  in  memory  from  within  DEBUG  and,  because  the  in¬ 
struction  hasn’t  executed  yet,  the  fix  can  be  tested  immediately.  To  make  the  correction, 
use  the  Assemble  Machine  Instructions  command,  A. 

-A  8  <Enter> 

1ACD:0008  int  21  <Enter> 
lACDrOOOA  <Enter> 

The  A  8  code  instructs  DEBUG  to  begin  assembling  at  CS:0008H.  DEBUG  prompts  with 
the  address  and  waits  for  an  instruction  to  be  entered.  The  letter  H  is  not  needed  after  the 
21  this  time  because  DEBUG  assumes  all  numbers  entered  with  the  Assemble  command 
are  in  hexadecimal  form.  In  general,  any  valid  8086/8087/8088  assembly-language  state¬ 
ment  can  be  entered  this  way  and  translated  into  executable  machine  code.  See 
PROGRAMMING  UTILITIES:  debug:  a.  Within  its  restrictions,  the  Assemble  command 
is  a  handy  way  of  making  changes.  The  Enter  Data  command,  E,  could  also  have  been 
used  to  change  the  15H  to  a  21H,  but  the  Assemble  command  is  safer,  especially  for  com¬ 
plex  instructions.  After  the  new  instruction  has  been  entered,  press  Enter  again  to  stop 
the  assembly  process. 

There  is  a  danger  associated  with  making  changes  in  memory  during  debugging:  The 
memory  copy  of  the  program  is  temporary;  the  changes  exist  only  in  memory  and  when 
DEBUG  exits,  they  are  lost.  Changes  made  to  .EXE  and  .HEX  files  cannot  be  written  back 
to  disk.  To  avoid  forgetting  the  changes,  write  them  down.  When  DEBUG  exits,  edit  the 
source  file  immediately.  Changes  made  to  other  files  can  be  written  back  to  disk  with 
DEBUG’S  Write  File  or  Sectors  command,  W. 

To  be  sure  that  the  change  was  made  correctly,  use  the  Disassemble  (Unassemble) 
Program  command,  U,  to  show  the  instructions  starting  at  CS:0004H. 


-U  4  <Enter> 

1ACD:0004  B406 

MOV 

AH, 06 

1ACD:0006 

B2FF 

MOV 

DL,FF 

1ACD:0008 

CD21 

INT 

21 

lACDiOOOA 

740C 

JZ 

0018 

1ACD:000C 

3C03 

CMP 

AL,03 

1ACD:000E 

7501 

JNZ 

0011 

1ACD:0010 

CB 

RETF 
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1ACD:001 1 

B401 

MOV 

AH,  01 

1ACD:0013 

BAOOOO 

MOV 

DX,0000 

1ACD:0016 

GDI  4 

INT 

14 

1ACD:0018 

B403 

MOV 

AH,  03 

lACDrOOIA 

BAOOOO 

MOV 

DXOOOO 

lACDiOOID 

CD14 

INT 

14 

lACDrOOIF 

80E401 

AND 

AH,  01 

1ACD:0022 

74E0 

JZ 

0004 

The  change  has  been  correctly  made.  Now,  to  test  the  change,  start  the  program  to  see  if 
characters  make  it  out  the  serial  port.  The  problem  of  data  from  the  serial  port  not  making 
it  to  the  screen  remains,  however,  so  instead  of  simply  starting  the  program,  set  a  break¬ 
point  at  the  location  in  the  program  that  handles  incoming  serial  data  (CS:0024H).  This 
technique  allows  the  output  section  of  the  code  to  be  tested  separately.  The  breakpoint  is 
set  using  the  Go  command,  G. 

-G  24  <Enter> 

AX=0130  BX=0000  CX=0131  DX=0000  SP=00FC  BP=0000  SI=0000  DI=0000 

DS=1AAD  ES=1AAD  SS=1ABD  CS=1ACD  IP=0024  NV  UP  El  PL  NZ  NA  PO  NC 


1ACD:0024  B402 

-U  <Enter> 

MOV 

AH,  02 

1ACD:0024 

B402 

MOV 

AH,  02 

1ACD:0026 

BAOOOO 

MOV 

DX,0000 

1ACD:0029 

GDI  4 

INT 

14 

1ACD:002B 

B406 

MOV 

AH,  06 

1ACD:002D 

GD21 

INT 

21 

1ACD:002F 

EBD3 

JMP 

0004 

1ACD:0031 

0000 

ADD 

[BX+SI],AL 

1ACD:0033 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0035 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0037 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0039 

0000 

ADD 

[BX+SI] ,AL 

1ACD:003B 

0000 

ADD 

[BX+SI] ,AL 

1ACD:003D 

0000 

ADD 

[BX+SI] ,AL 

1ACD:003F 

0000 

ADD 

[BX+SI] ,AL 

1ACD;0041 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0043 

0000 

ADD 

[BX+SI] ,AL 

As  stated  earlier,  the  serial  port  is  attached  to  a  serial  terminal.  After  execution  of  the  pro¬ 
gram  is  started  with  the  Go  command,  all  keys  typed  on  the  keyboard  are  displayed  cor¬ 
rectly  on  the  terminal,  thus  confirming  the  fix  made  to  the  INT  21H  instruction.  To  test 
serial  input,  a  key  must  be  pressed  on  the  terminal,  causing  the  breakpoint  at  CS:0024H 
to  be  executed. 

The  fact  that  location  CS:0024H  was  reached  indicates  that  Interrupt  14H  is  detecting  the 
presence  of  an  input  character.  To  test  if  the  character  is  now  making  it  to  the  screen,  a 
breakpoint  is  needed  after  the  write  to  the  screen.  The  Disassemble  command  shows  the 
instructions  starting  at  the  current  IP  value.  The  program  ends  at  CS:002FH;  the  instruc¬ 
tions  shown  after  that  are  whatever  happened  to  be  in  memory  when  the  program  was 
loaded.  A  good  place  to  set  the  next  breakpoint  is  CS:002FH,  just  after  the  Interrupt  21H 
call. 
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-G  2f  <Enter> 

AX=0600  BX=0000  CX=0131  DX=0000  SP=00FC  BP=0000  SI=0000  DI=0000 

DS=1AAD  ES=1AAD  SS=1ABD  CS=1ACD  IP=002F  NV  UP  El  PL  NZ  NA  PO  NC 

1ACD:002F  EBD3  JMP  0004 

DEBUG  shows  that  the  breakpoint  was  reached  and  the  character  did  not  print  (it  should 
have  been  on  the  line  after  -G  2f\  so  something  must  be  wrong  with  the  Interrupt  21H 
call.  A  breakpoint  just  before  the  MS-DOS  call  at  CS:002DH  should  reveal  the  cause  of  the 
problem. 

-G  2d  <Enter> 

AX=0662  BX=0000  CX=0131  DX=0000  SP=00FC  BP=0000  SI=0000  DI=0000 

DS=1AAD  ES=1AAD  SS=1ABD  CS=1ACD  IP=002D  NV  UP  El  PL  NZ  NA  PO  NC 

1ACD:002D  CD21  INT  21 

The  key  that  was  entered  on  the  serial  terminal  (b)  is  in  AL,  where  it  was  returned  by 
Interrupt  14H.  Unfortunately,  it  is  not  in  DL,  where  it  is  expected  by  the  Direct  Console  I/O 
function  (06H)  of  the  MS-DOS  command.  The  MS-DOS  function  was  simply  printing  a  null 
(OOH)  and  then  moving  the  cursor.  An  instruction  (MOV  DL,AL)  is  missing. 

Fixing  this  problem  requires  the  insertion  of  a  line  of  code,  which  is  usually  difficult  to  do 
inside  DEBUG.  The  Move  (Copy)  Data  command,  M,  can  be  used  to  move  the  code  located 
below  the  point  where  the  insertion  is  to  be  made  down  2  bytes,  but  this  will  probably 
throw  any  subsequent  addressing  off.  It  is  usually  easier  to  exit  DEBUG,  edit  the  source  file, 
and  then  reassemble.  In  this  case,  however,  because  the  instruction  to  be  added  is  near  the 
last  instruction,  a  patch  can  easily  be  made  by  entering  only  three  instructions:  the  new 
one  and  the  two  it  destroys. 

-A  2d  <Enter> 


1ACD:002D 

mov  dl. 

al  <Enter> 

1ACD:002F 

int  21 

<Enter> 

1ACD:0031 

jmp  4 

<Enter> 

1ACD:0033 

<Enter> 

-U  2b  <Enter> 

1ACD:002B 

B406 

MOV 

AH,  06 

1ACD:002D 

88C2 

MOV 

DL,AL 

1ACD:002F 

CD21 

INT 

21 

1ACD:0031 

EBD1 

JMP 

0004 

1ACD:0033 

0000 

ADD 

[BX+SI] ,AL 

1ACD;0035 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0037 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0039 

0000 

ADD 

[BX+SI] ,AL 

1ACD;003B 

0000 

ADD 

[BX+SI] ,AL 

1ACD;003D 

0000 

ADD 

[BX+SI] ,AL 

1ACD:003F 

0000 

ADD 

[BX+SI] ,AL 

1ACD;0041 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0043 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0045 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0047 

0000 

ADD 

[BX+SI] ,AL 

1ACD:0049 

0000 

ADD 

[BX+SI] ,AL 
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The  new  line  of  code  has  been  inserted  and  verified  with  the  Disassemble  command.  The 
fix  is  ready  to  test.  The  Trace  command  could  be  used  to  single-step  through  the  program 
to  verify  execution.  A  word  of  warning  is  in  order,  however:  The  DEBUG  Trace  command 
should  never  be  used  to  trace  an  Interrupt  21H  call.  Once  the  trace  enters  the  MS-DOS  call, 
it  will  wander  around  for  a  while  and  then  lock  the  machine,  requiring  a  restart.  Avoid  this 
problem  either  by  setting  a  breakpoint  just  beyond  the  Interrupt  21H  call  or  by  using  the 
Proceed  Through  Loop  or  Subroutine  command,  P.  The  Proceed  command  operates  in  a 
similar  manner  to  the  Trace  command  but  does  not  trace  loops,  calls,  and  interrupts. 

Because  the  fix  is  fairly  certain,  use  the  Go  command  in  its  simple  form  with  no  break¬ 
points.  The  program  will  execute  without  further  intervention  from  DEBUG. 

-G  <Enter> 
lasdfgh 

Program  terminated  normally 
-Q  <Enter> 

The  lasdfgh  text  entered  on  the  serial  terminal  is  displayed  correctly.  When  a  Ctrl-C  is 
entered  from  the  keyboard,  the  program  terminates  properly  and  DEBUG  displays  the 
message  Program  terminated  normally.  Now  exit  DEBUG  with  the  Quit  command,  Q. 

The  source  code  of  TESTCOMM  should  be  edited  immediately  so  that  it  reflects  the  two 
changes  made  temporarily  under  DEBUG.  Figure  18-10  shows  the  corrected  listing. 

TITLE  TESTCOMM  -  TEST  COMMSCOP  ROUTINE 


*  ♦ 

*  TESTCOMM  * 

*  THIS  ROUTINE  PROVIDES  DATA  FOR  THE  COMMSCOP  ROUTINE.  IT  READS  * 

*  CHARACTERS  FROM  THE  KEYBOARD  AND  WRITES  THEM  TO  COM1  USING  * 

*  INT  14H.  DATA  IS  ALSO  READ  FROM  INT  1 4H  AND  DISPLAYED  ON  THE  * 

*  SCREEN.  THE  ROUTINE  RETURNS  TO  MS-DOS  WHEN  Ctrl-C  IS  PRESSED  * 

*  ON  THE  KEYBOARD.  * 

*  * 


SSEG  SEGMENT  PARA  STACK  'STACK' 

DW  128  DUP(?) 

SSEG  ENDS 

CSEG  SEGMENT 

ASSUME  CS : CSEG, SS: SSEG 
BEGIN  PROC  FAR 

PUSH  DS 

XOR  AX, AX 

PUSH  AX 


;SET  UP  FOR  RET  TO  MS-DOS 


Figure  18-10.  Correct  serial  test  routine. 


(more) 
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MAINLOOP : 


MOV 

AH,  6 

•USE  DOS  CALL  TO  CHECK  FOR 

MOV 

DL, OFFH 

KEYBOARD  ACTIVITY 

I  NT 

21H 

IF  NO  CHARACTER,  JUMP  TO 

JZ 

TESTCOMM 

COMM  ACTIVITY  TEST 

CMP 

AL,  03 

WAS  CHARACTER  A  Ctrl-C? 

JNE 

SENDCOMM 

NO,  SEND  IT  TO  SERIAL  PORT 

RET 

YES,  RETURN  TO  MS-DOS 

SENDCOMM: 

MOV 

AH,  01 

USE  INT  14H  WRITE  FUNCTION  TO 

MOV 

DX,0 

SEND  DATA  TO  SERIAL  PORT 

INT 

1  4H 

TESTCOMM: 

MOV 

AH,  3 

GET  SERIAL  PORT  STATUS 

MOV 

DX,  0 

. 

INT 

1  4H 

. 

AND 

AH,  1 

ANY  DATA  WAITING? 

JZ 

MAINLOOP 

NO,  GO  BACK  TO  KEYBOARD  TEST 

MOV 

AH,  2 

READ  SERIAL  DATA 

MOV 

DX,  0 

. 

INT 

14H 

. 

MOV 

AH,  6 

WRITE  SERIAL  DATA  TO  SCREEN 

MOV 

DL,AL 

. 

INT 

21H 

. 

JMP 

MAINLOOP 

CONTINUE 

BEGIN 

ENDP 

CSEG 

ENDS 

END 

BEGIN 

Figure  18-10.  Continued. 

DEBUG  has  a  rich  set  of  commands  and  features.  The  preceding  case  study  shows  the 
more  common  ones  in  their  most  straightforward  aspect.  Some  of  the  other  commands 
and  some  useful  techniques  are  described  below.  See  PROGRAMMING  UTILITIES: 

DEBUG. 

Establishing  initial  conditions 

When  a  program  is  loaded  for  testing,  four  areas  may  require  initialization: 

•  Registers 

•  Data  areas 

•  Default  file-control  blocks  (FCBs) 

•  Command  tail 

These  areas  may  also  require  changes  during  testing,  especially  when  the  programmer  is 
working  around  bugs  or  establishing  different  test  conditions. 
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Registers.  Registers  are  ordinarily  set  when  the  program  is  loaded.  The  values  in  them 
depend  on  whether  a  .EXE,  .COM,  or  .HEX  file  was  loaded.  Generally,  the  segment  regis¬ 
ters,  the  IP  register,  and  the  SP  register  are  set  to  appropriate  values;  with  the  exception  of 
AX,  BX,  and  CX,  the  rest  of  the  registers  are  set  to  zero.  BX  and  CX  contain  the  length  of 
the  loaded  file.  By  MS-DOS  convention,  when  a  program  is  loaded,  the  contents  of  AL  and 
AH  indicate  the  validity  of  the  drive  specifiers  in  the  first  and  second  DEBUG  command¬ 
line  parameters,  respectively.  Each  register  contains  zero  if  the  corresponding  drive  was 
valid,  OlH  if  the  drive  was  valid  and  wildcards  were  used,  or  OFFH  if  the  drive  was  invalid. 

To  change  the  value  of  any  register,  use  an  alternate  form  of  the  Register  command.  Enter 
R  followed  by  the  two-letter  register  name.  Only  l6-bit  registers  can  be  changed,  so  use  the 
X  form  of  the  general-purpose  registers: 

-R  AX  <Enter> 

DEBUG  will  respond  with  the  current  contents  of  the  register  and  prompt  for  a  new  value. 
Either  enter  a  new  hexadecimal  value  or  press  Enter  to  keep  the  current  value; 

AX  0000 
:FFFF  <Enter> 

In  this  example,  the  new  value  of  AX  is  FFFFH. 

When  changing  registers,  exercise  caution  modifying  the  segment  registers.  These  regis¬ 
ters  control  the  execution  of  the  program  and  should  be  changed  only  after  careful  and 
thoughtful  consideration. 

The  Register  command  can  also  be  used  to  modify  the  CPU  flags. 

Data  areas.  Initializing  or  changing  data  areas  is  easy,  and  several  methods  are  provided. 
The  Fill  Memory  command,  F,  can  be  used  to  initialize  areas  of  RAM.  For  instance, 

-F  0  L400  0  <Enter> 

fills  DS:0000H  through  DS:03FFH  with  zero.  (The  absence  of  a  segment  override  causes 
the  Fill  command  to  use  its  default  segment,  DS.)  Entering 

-F  CS:100  200  IB  "[Hello”  OD  <Enter> 

fills  CSiOlOOH  through  CS:0200H  with  many  repetitions  of  the  string  IB  5B  48  65  6C  6C  6F 
OD.  (Note  that  an  address  range  was  specified,  not  a  length.) 

When  the  wholesale  changing  of  memory  is  not  appropriate,  the  Enter  command  can  be 
used  to  edit  a  small  number  of  locations.  The  Enter  command  has  two  forms:  One  enters  a 
list  of  bytes  into  the  specified  memory  location;  the  other  prompts  with  the  contents  of 
each  location  and  waits  for  input.  Either  form  can  be  used  as  appropriate. 

Default file-control  blocks  and  the  command  tail.  The  setting  of  the  default  FCBs  and 
of  the  command  tail  are  related  functions.  When  DEBUG  is  entered,  the  first  parameter 
following  the  command  DEBUG  is  the  name  of  the  file  to  be  loaded  into  memory  for 
debugging.  If  the  next  two  parameters  are  filenames,  FCBs  for  these  files  are  formatted  at 
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DS:005CH  and  DS:006CH  in  the  PSP.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRON¬ 
MENT:  Programming  for  ms-dos:  File  and  Record  Management.  If  either  parameter  con¬ 
tains  a  pathname,  the  corresponding  FCB  will  contain  only  a  valid  drive  number;  the 
filename  field  will  not  be  valid.  All  filenames  and  switches  following  the  name  of  the  file 
to  be  debugged  are  considered  the  command  tail  and  are  saved  in  memory  starting  at 
DS:0081H.  The  length  of  the  command  tail  is  in  DS:0080H.  For  example,  entering 

ODEBUG  COMMDUMP.EXE  FILE1.DAT  FILE2.DAT  <Enter> 

results  in  the  first  FCB  (5CH),  the  second  FCB  (6CH),  and  the  command  tail  (81H)  being 
loaded  as  follows: 

-D  50  <Enter> 

42C9:0050  CD  21  CB  00  00  00  00  00-00  00  00  00  00  46  49  4C 

42C9:0060  45  31  20  20  20  44  41  54-00  00  00  00  00  46  49  4C 

42C9:0070  45  32  20  20  20  44  41  54-00  00  00  00  00  00  00  00 

42C9:0080  15  20  66  69  6C  65  31  2E-64  61  74  20  66  69  6C  65 

42C9:0090  32  2E  64  61  74  20  OD  74-20  66  69  6C  65  32  2E  64 

42C9:00A0  61  74  20  OD  00  00  00  00-00  00  00  00  00  00  00  00 

42C9:00B0  00  00  00  00  00  00  00  00-00  00  00  00  00  00  00  00 

42C9:00C0  00  00  00  00  00  00  00  00-00  00  00  00  00  00  00  00 

In  this  example,  location  DS:005CH  contains  an  unopened  FCB  for  file  FILE1.DAT  on  the 
current  drive.  Location  DS:006CH  contains  an  unopened  FCB  for  FILE2.DAT  on  the  current 
drive.  (The  second  FCB  cannot  be  used  where  it  is  and  must  be  moved  to  another  location 
before  the  first  FCB  is  opened.)  Location  DS:0080H  contains  the  length  of  the  command 
tail,  15H  (21)  bytes.  The  next  21  bytes  are  the  command  tail  prepared  by  DEBUG;  they  cor¬ 
respond  exactly  to  what  the  command  tail  would  be  if  the  program  had  been  loaded  by 
COMMAND.COM  instead  of  by  DEBUG. 

The  default  FCBs  and  the  command  tail  can  also  be  set  after  the  program  has  been  loaded, 
by  using  the  Name  File  or  Command-Tail  Parameters  command,  N.  DEBUG  treats  the 
string  of  characters  that  follow  the  Name  command  as  the  command  tail:  If  the  first  two 
parameters  are  filenames,  they  become  the  first  and  second  FCBs,  respectively.  The  Name 
command  also  places  the  string  at  DS:0081H,  with  the  length  of  the  string  at  DS:0080H. 
Entering  the  DEBUG  command 

-N  FILE1.DAT  FILE2.DAT  <Enter> 

produces  the  same  results  as  specifying  the  filenames  in  the  command  line.  When  em¬ 
ployed  in  this  manner,  the  Name  command  is  useful  for  initializing  command-tail  data  that 
was  not  in  the  command  line  or  for  changing  the  command-tail  data  to  test  different 
aspects  of  a  program.  (If  files  are  named  in  this  manner,  they  are  not  validated  until  the 
Load  File  or  Sectors  command,  L,  is  used.)  Note  that  the  data  following  the  Name  com¬ 
mand  need  not  be  filenames;  it  can  be  any  parameters,  data,  or  switches  that  the  applica¬ 
tion  program  expects  to  see. 


.  ! . FIL 

El  DAT . FIL 

E2  DAT . 

.  filel .dat  file 
2.dat  .t  file2.d 
at  . 
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More  on  breakpoints 

The  case  study  at  the  beginning  of  this  section  used  breakpoints  in  their  simplest  form: 
Only  a  single  breakpoint  was  specified  at  a  time  and  the  execution  address  was  con¬ 
sidered  to  be  the  current  IP.  The  Go  command  is  also  capable  of  setting  multiple  break¬ 
points  and  of  beginning  execution  at  any  address  in  memory.  The  more  general  form  of 
the  Go  command  is 

G{=address]  [address  [address. . . ]] 

If  Go  is  used  with  no  operands,  execution  begins  at  the  current  value  of  CS:IP  and  no 
breakpoints  are  set.  If  the  =address  operand  is  used,  DEBUG  sets  IP  to  the  address  speci¬ 
fied  and  execution  then  begins  at  the  new  CS:IP.  The  other  optional  addresses  are  break¬ 
points.  When  execution  reaches  one  of  these  breakpoints,  DEBUG  stops  and  displays  the 
system’s  registers.  As  many  as  10  breakpoints  can  be  set  on  one  Go  command,  and  they 
can  be  in  any  order. 

The  breakpoint  addresses  must  be  on  instruction  boundaries  because  DEBUG  replaces 
the  instruction  at  each  breakpoint  address  with  an  INT  03H  instruction  (OCCH).  DEBUG 
saves  the  replaced  instructions  internally.  When  any  breakpoint  is  reached,  DEBUG  stops 
execution  and  restores  the  instructions  at  all  the  breakpoints;  if  no  breakpoint  is  reached, 
the  instructions  are  not  restored  and  the  Load  command  must  be  used  to  reload  the  origi¬ 
nal  program. 

The  multiple-breakpoint  feature  of  the  Go  command  allows  the  tracing  of  program  exe¬ 
cution  when  branches  exist  in  the  code.  When  a  program  contains,  for  instance,  a  condi¬ 
tional  jump  on  the  zero  flag,  a  breakpoint  can  be  placed  in  each  of  the  two  possible 
branches.  When  the  branch  is  reached,  one  of  the  two  breakpoints  will  be  encountered 
shortly  thereafter.  When  DEBUG  displays  the  breakpoint,  the  programmer  knows  which 
branch  was  taken.  Moving  through  a  program  with  breakpoints  at  key  locations  is  faster 
than  using  the  Trace  command  to  execute  each  and  every  instruction. 

Multiple  breakpoints  can  also  be  used  to  home  in  on  a  bad  piece  of  code.  This  technique 
is  particularly  useful  in  those  nasty  situations  when  there  are  no  symptoms  except  that  the 
system  locks  up  and  must  be  restarted.  When  debugging  a  problem  such  as  this,  set  break¬ 
points  at  each  of  the  major  sections  of  the  program  and  then  note  those  breakpoints  that 
are  executed  successfully,  continuing  until  the  system  locks  up.  The  problem  lies  some¬ 
where  between  the  last  successful  breakpoint  and  the  next  breakpoint  set.  Now  repeat  the 
processes,  setting  breakpoints  between  the  last  breakpoint  and  the  one  that  was  never 
reached.  By  progressively  narrowing  the  gap  between  breakpoints,  the  exact  offending 
instruction  can  be  isolated. 

Some  general  comments  about  the  Go  command  and  breakpoints: 

•  After  a  program  has  reached  completion  and  returned  to  MS-DOS,  it  must  be  reloaded 
with  the  Load  command  before  it  can  be  executed  again.  (DEBUG  intercepts  this 
return  and  displays  Program  terminated  normally^ 

•  Because  DEBUG  replaces  program  instructions  with  an  INT  03H  instruction  to  form 
breakpoints,  the  break  address  must  be  on  an  instruction  boundary.  If  it  is  not,  the 
INT  03H  will  be  stuck  in  the  middle  of  an  instruction,  causing  strange  and  sometimes 
entertaining  results. 
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•  Breakpoints  cannot  be  set  in  data,  because  data  is  not  executed. 

•  The  target  program’s  SS:SP  registers  must  point  to  a  valid  stack  that  has  at  least  6  bytes 
of  stack  space  available.  When  the  Go  command  is  executed,  it  pushes  the  target  pro¬ 
gram’s  flags  and  CS  and  IP  registers  onto  the  stack  and  then  transfers  control  to  the 
program  with  an  IRET  instruction.  Thus,  if  the  target  program’s  stack  is  not  valid  or 

is  too  small,  the  system  may  crash. 

•  Finally,  and  obviously,  breakpoints  cannot  be  set  in  read-only  memory  (the  ROM 
BIOS,  for  instance). 

Using  the  Write  commands 

After  a  program  has  been  debugged,  fixed,  and  tested  with  DEBUG,  the  temptation  exists 
to  write  the  patched  program  directly  back  to  the  disk  as  a  .COM  file.  This  action  is  some¬ 
times  legitimate,  but  only  rarely.  The  technique  will  be  explained  in  a  moment,  but  first  a 
sermon: 

DONTDOIT. 

One  of  the  greatest  sadnesses  in  a  programmer’s  life  comes  when,  after  a  program  has 
been  running  wonderfully,  enhancements  are  made  to  the  source  code  and  the  recom¬ 
piled  program  suddenly  has  bugs  in  it  that  haven’t  been  seen  for  months.  Always  make  any 
debugging  patches  permanent  in  the  source  file  immediately. 

Unless,  of  course,  the  source  code  is  not  available.  This  is  the  only  time  saving  a  patched 
program  is  permissible.  For  example,  sometimes  commercial  programs  require  patching 
because  the  program  does  not  quite  fit  the  hardware  it  must  run  on  or  because  bugs  have 
been  found  in  the  program.  The  source  of  these  patches  is  sometimes  word-of-mouth, 
sometimes  a  bulletin-board  service,  and  sometimes  the  program’s  manufacturer. 

Even  when  legitimate  reasons  exist  to  save  patched  code,  precautions  should  be  taken.  Be 
very  careful,  meticulous,  and  alert  as  the  patches  are  applied.  Understand  each  step  before 
undertaking  it.  Most  important  of  all,  always  have  a  backup  of  the  original  unpatched 
program  safely  on  a  floppy  disk. 

Use  the  Write  command  to  write  the  program  image  to  disk.  A  starting  address  can  op¬ 
tionally  be  specified;  otherwise  the  write  starts  at  CS:0i00H.  The  name  of  the  file  will  be 
either  the  name  specified  in  the  last  Name  command  or  the  name  of  the  program  from  the 
DEBUG  command  line  if  the  Name  command  has  not  been  used.  The  number  of  bytes  to 
be  written  is  in  BX  and  CX,  with  the  most  significant  half  in  BX.  These  registers  will  have 
been  loaded  correctly  when  the  program  was  loaded,  but  they  should  be  checked  if  the 
program  has  executed  since  it  was  loaded. 

The  .EXE  and  .HEX  file  types  cannot  be  written  to  disk  with  the  Write  command.  The 
command  performs  no  formatting  and  only  writes  the  binary  image  of  memory  to  the  disk 
file.  Thus,  all  programs  written  with  Write  must  be  .COM  files.  The  image  of  a  .EXE  or 
.HEX  file  can  still  be  written  as  a  .COM  file  provided  no  segment  fixups  are  required  and 
provided  the  other  rules  for  a  .COM  file  are  followed.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Structure  of  an  Application  Program. 
(A  segment  fixup  is  a  segment  address  that  must  be  provided  by  the  loader  when  the 
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program  is  originally  loaded.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Pro¬ 
gramming  Tools:  Object  Modules.)  If  a  .EXE  file  containing  a  segment  fixup  is  written  as  a 
.COM  file,  the  new  file  will  execute  correctly  only  when  loaded  at  exactly  the  same  address 
as  the  original  file,  and  this  is  difficult  to  ensure  for  programs  running  under  MS-DOS. 

If  it  is  necessary  to  patch  a  .EXE  or  .HEX  file  and  the  exact  addresses  relative  to  the  start  of 
the  file  are  known,  use  the  following  procedure: 

1.  Rename  (or  better  yet,  copy)  the  file  to  an  extension  other  than  .EXE  or  .HEX. 

2.  Load  the  program  image  into  memory  by  placing  the  new  name  on  DEBUG’s  com¬ 
mand  line.  Note  that  the  loaded  file  is  an  image  of  the  disk  file  and  is  not  executable. 

3.  Modify  the  program  image  in  memory,  but  never  try  to  execute  the  program.  Results 
would  be  unpredictable  and  the  program  image  could  be  damaged. 

4.  Write  the  modified  image  back  to  disk  using  a  simple  w.  No  other  action  is  needed, 
because  the  original  load  will  have  set  the  filename  and  the  correct  length  in  BX 
andCX. 

5.  Rename  the  file  to  a  name  with  the  correct  .EXE  or  .HEX  extension.  The  new  name 
need  not  be  the  same  as  the  original,  but  it  should  have  the  same  extension. 

The  same  technique  can  be  used  to  load,  modify,  and  save  data  files.  Simply  make  sure 
that  the  file  does  not  have  an  extension  of  .COM,  .EXE,  or  .HEX.  The  data  file  will  be 
loaded  at  address  CS:0100H.  (DEBUG  treats  the  file  much  the  same  as  a  .COM  file.)  After 
patching  the  data  (the  Enter  command  works  best),  use  the  Write  command  to  write  it 
back  to  the  disk. 

SYMDEB 

SYMDEB  is  an  extension  of  DEBUG;  virtually  all  the  DEBUG  commands  and  techniques 
still  work  as  expected.  The  major  new  feature,  and  the  source  of  the  name  SYMDEB,  is 
symbolic  debugging:  SYMDEB  can  use  all  public  labels  in  a  program  for  reference,  instead 
of  using  hexadecimal  offset  addresses.  In  addition,  SYMDEB  allows  the  use  of  line  num¬ 
bers  for  reference  in  compatible  high-order  languages;  source-line  display  within  SYMDEB 
is  also  possible  for  these  languages.  Currently,  the  languages  supporting  these  options  are 
Microsoft  FORTRAN  versions  3.0  and  later,  Microsoft  Pascal  versions  3.0  and  later,  and 
Microsoft  C  versions  2.0  and  later.  Versions  4.0  and  earlier  of  the  Microsoft  Macro  Assem¬ 
bler  (MASM)  do  not  generate  the  data  needed  for  line-number  display  and  source-line 
debugging. 

In  addition  to  symbolic  debugging,  SYMDEB  has  added  several  other  new  features  and  has 
expanded  existing  DEBUG  features: 

•  Breakpoints  have  been  made  more  sophisticated  with  the  addition  of  “sticky” 
breakpoints.  Unlike  the  breakpoints  set  with  the  Go  command,  sticky  breakpoints 
remain  attached  to  the  program  throughout  a  SYMDEB  session  until  they  are  explic¬ 
itly  removed.  Specific  commands  are  supplied  for  listing,  removing,  enabling,  and 
disabling  sticky  breakpoints. 

•  DEBUG’S  Display  Memory  command,  D,  has  been  extended  so  that  data  can  be 
displayed  in  different  formats. 
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•  Full  redirection  is  supported. 

•  A  stack  trace  feature  has  been  added. 

•  Terminate-and-stay-resident  programs  are  supported. 

•  A  shell  escape  command  has  been  added  to  allow  the  execution  of  MS-DOS 
commands  and  programs  without  leaving  SYMDEB  and  the  debugging  session. 

These  additions  allow  more  sophisticated  debugging  techniques  to  be  used  and,  in  some 
cases,  also  simplify  locating  problems.  To  see  the  advantages  of  using  symbols  and  sticky 
breakpoints  in  debugging,  consider  a  type  of  program  that  is  one  of  the  most  difficult  to 
debug — the  TSR. 

Debugging  TSRs  with  SYMDEB 

Terminate-and-stay-resident  routines  can  be  difficult  to  debug.  They  exist  in  two  worlds 
and  can  have  bugs  associated  with  each.  At  the  outset,  they  are  usually  simple  programs 
that  perform  some  initialization  task  and  then  exit.  At  this  point,  they  are  transformed  into 
another  type  of  beast  entirely — resident  routines  that  are  more  a  part  of  the  operating  sys¬ 
tem  than  of  any  application  program.  Each  form  of  the  program  must  be  debugged  sepa¬ 
rately,  using  different  techniques. 

The  TSR  routine  used  for  this  case  study  is  the  same  one  created  previously  to  serve 
as  external  instrumentation  to  trace  serial  communications.  The  program  was  called 
COMMSCOP,  but  to  avoid  confusion  of  that  working  program  with  the  broken  one  pre¬ 
sented  here,  the  name  has  been  changed  to  BADSCOP.  BADSCOP  was  assembled  and 
linked  in  the  usual  manner  and  then  converted  to  a  .COM  file  using  EXE2BIN.  When  it  was 
installed,  it  returned  normally,  but  at  the  first  attempt  to  issue  an  Interrupt  14H,  the  system 
locked  up  completely.  Warm  booting  was  not  sufficient  to  restore  it,  and  a  power-on  cold 
boot  was  required  to  get  the  system  working  again. 

Figure  18-11  is  a  listing  of  BADSCOP.  The  only  difference  from  COMMSCOP,  aside  from  the 
errors,  is  the  addition  of  two  PUBLIC  statements  to  make  all  the  procedure  names  and  the 
important  data  names  available  to  SYMDEB. 

TITLE  BADSCOP  -  BAD  VERSION  OF  COMMUNICATIONS  TRACE  UTILITY 


;  *  * 

;  *  BADSCOP  -  * 

;  *  THIS  PROGRAM  MONITORS  THE  ACTIVITY  ON  A  SPECIFIED  COMM  PORT  * 

;  *  AND  PLACES  A  COPY  OF  ALL  COMM  ACTIVITY  IN  A  RAM  BUFFER.  EACH  * 

;  *  ENTRY  IN  THE  BUFFER  IS  TAGGED  TO  INDICATE  WHETHER  THE  BYTE  * 

;  *  WAS  SENT  BY  OR  RECEIVED  BY  THE  SYSTEM.  * 

;  *  * 

;  *  BADSCOP  IS  INSTALLED  BY  ENTERING  * 

;  *  * 

;  *  BADSCOP  * 

;  *  * 

Figure  18-11.  An  incorrect  version  of  the  serial  trace  utility.  ( more) 
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*  THIS  WILL  INSTALL  BADSCOP  AND  SET  UP  A  64K  BUFFER  TO  BE  USED  * 

*  FOR  DATA  LOGGING.  REMEMBER  THAT  2  BYTES  ARE  REQUIRED  FOR  * 

*  EACH  COMM  BYTE,  SO  THE  BUFFER  IS  ONLY  32K  EVENTS  LONG,  OR  ABOUT  * 

*  30  SECONDS  OF  CONTINUOUS  9600  BAUD  DATA.  IN  THE  REAL  WORLD,  * 

*  ASYNC  DATA  IS  RARELY  CONTINUOUS,  SO  THE  BUFFER  WILL  PROBABLY  * 

*  HOLD  MORE  THAN  30  SECONDS  WORTH  OF  DATA.  * 

He  * 

*  WHEN  INSTALLED,  BADSCOP  INTERCEPTS  ALL  INT  1 4H  CALLS.  IF  THE  * 

*  PROGRAM  HAS  BEEN  ACTIVATED  AND  THE  INT  IS  EITHER  SEND  OR  RE-  * 

*  CEIVE  DATA,  A  COPY  OF  THE  DATA  BYTE,  PROPERLY  TAGGED,  IS  PLACED  * 


*  IN  THE  BUFFER.  IN  ANY  CASE,  DATA  IS  PASSED  ON  TO  THE  REAL  * 

*  INT  14H  HANDLER.  * 

He  * 

*  BADSCOP  IS  INVOKED  BY  ISSUING  AN  INT  60H  CALL.  THE  INT  HAS  * 

*  THE  FOLLOWING  CALLING  SEQUENCE:  * 

He  He 

*  AH  -  COMMAND  * 

*  0  -  STOP  TRACING,  PLACE  STOP  MARK  IN  BUFFER  * 

*  1  -  FLUSH  BUFFER  AND  START  TRACE  * 

*  2  -  RESUME  TRACE  * 

*  3  -  RETURN  COMM  BUFFER  ADDRESSES  * 

*  DX  -  COMM  PORT  (ONLY  USED  WITH  AH  =  1  or  2)  * 

*  0  -  COM1  * 

*  1  -  COM2  * 

He  He 

*  THE  FOLLOWING  DATA  IS  RETURNED  IN  RESPONSE  TO  AH  =  3 :  * 

He  He 

*  ex  -  BUFFER  COUNT  IN  BYTES  * 

*  DX  -  SEGMENT  ADDRESS  OF  THE  START  OF  THE  BUFFER  * 

*  BX  -  OFFSET  ADDRESS  OF  THE  START  OF  THE  BUFFER  * 

He  He 

*  THE  COMM  BUFFER  IS  FILLED  WITH  2-BYTE  DATA  ENTRIES  OF  THE  ♦ 

*  FOLLOWING  FORM:  * 

He  He 

*  BYTE  0  -  CONTROL  * 

*  BIT  0  -  ON  FOR  RECEIVED  DATA,  OFF  FOR  TRANS.  * 

*  BIT  7  -  STOP  MARK  -  INDICATES  COLLECTION  WAS  * 

*  INTERRUPTED  AND  RESUMED.  * 

*  BYTE  1  -  8-BIT  DATA  * 

He  He 


PUBLIC  INITIALIZE, CONTROL, VECTOR_INIT,COMMSCOPE 
PUBLIC  OLD_COMM_INT, COUNT, STATUS, PORT, BUFPNTR 

CSEG  SEGMENT 

ASSUME  CS : CSEG, DS: CSEG 

ORG  100H  ;TO  MAKE  A  COM  FILE 

Figure  18-11.  Continued. 


(more) 
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INITIALIZE: 

JMP  VECTOR_INIT 


;JUMP  TO  THE  INITIALIZATION 
;  ROUTINE  WHICH,  TO  SAVE  SPACE, 
;  IS  IN  THE  COMM  BUFFER 


SYSTEM  VARIABLES 


OLD_COMM_INT 

DD 

7 

/ADDRESS  OF  REAL  COMM  INT 

COUNT 

DW 

0 

/BUFFER  COUNT 

COMMSCOPE_INT 

EQU 

60H 

/COMMSCOPE  CONTROL  INT 

STATUS 

DB 

0 

/PROCESSING  STATUS 

/  0  -  OFF 

/  1  -  ON 

PORT 

DB 

0 

/COMM  PORT  BEING  TRACED 

BUFPNTR 

DW 

VECTOR_INIT 

/NEXT  BUFFER  LOCATION 

SUBTTL  DATA  INTERRUPT  HANDLER 

PAGE 

*  * 

*  COMMSCOPE  * 

*  THIS  PROCEDURE  INTERCEPTS  ALL  INT  1 4H  CALLS  AND  LOGS  THE  DATA  * 

*  IF  APPROPRIATE.  * 

♦ 


;ARE  WE  ON? 

;  NO,  SIMPLY  JUMP  TO  OLD  HANDLER 
/SKIP  SETUP  CALLS 


/  * 

COMMSCOPE 

PROC  NEAR 

TEST 

CS: STATUS, 1 

JZ 

OLD_JUMP 

CMP 

AH, OOH 

JE 

OLD_JUMP 

CMP 

AH,03H 

JAE 

OLD_JUMP 

CMP 

AH, 02H 

JE 

GET_READ 

/  DATA  WRITE 

REQUEST  -  SAVE 

CMP 

DL,CS:PORT 

JNE 

OLD_JUMP 

PUSH 

DS 

PUSH 

BX 

PUSH 

CS 

POP 

DS 

MOV 

BX, BUFPNTR 

/SKIP  STATUS  REQUESTS 


/IS  THIS  A  READ  REQUEST? 
/  YES,  GO  PROCESS 


/IS  WRITE  FOR  PORT  BEING  TRACED? 

/  NO,  JUST  PASS  IT  THROUGH 

SAVE  CALLER'S  REGISTERS 

SET  UP  DS  FOR  OUR  PROGRAM 

GET  ADDRESS  OF  NEXT  BUFFER  LOCATION 


Figure  18-11.  Continued. 
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MOV 

[BX],BYTE  PTR  0 

MOV 

[BX+1 ] ,AL 

INC 

COUNT 

INC 

COUNT 

INC 

BX 

INC 

BX 

MOV 

BUFPNTR, BX 

JNZ 

WRITE-DONE 

MOV 

WRITE-DONE: 

STATUS, 0 

POP 

BX 

POP 

DS 

JMP 

OLD-JUMP 

;  PROCESS  A  READ  DATA  REQUEST  AND  WRITE 
GET_READ : 

CMP  DL,CS:PORT 

JNE  OLD_JUMP 

PUSH  DS 

PUSH  BX 

PUSH  CS 

POP  DS 

PUSHF 

CLI 

CALL  OLD_COMM_INT 

TEST  AH,80H 

JNZ  READ-DONE 

MOV  BX,BUFPNTR 

MOV  [BX],BYTE  PTR  1 

MOV  [BX+1],AL 

INC  COUNT 

INC  COUNT 

INC  BX 

INC  BX 

MOV  BUFPNTR, BX 

JNZ  READ-DONE 

MOV  STATUS, 0 

READ-DONE : 

POP  BX 

POP  DS 

I  RET 


;  JUMP  TO  COMM  BIOS  ROUTINE 
OLD-JUMP : 

JMP  OLD-COMM-INT 


MARK  AS  TRANSMITTED  BYTE 
SAVE  DATA  IN  BUFFER 
INCREMENT  BUFFER  BYTE  COUNT 

POINT  TO  NEXT  LOCATION 

SAVE  NEW  POINTER 

ZERO  INDICATES  BUFFER  HAS  WRAPPED 
/TURN  COLLECTION  OFF  -  BUFFER  FULL 
/RESTORE  CALLER'S  REGISTERS 
/PASS  REQUEST  ON  TO  BIOS  ROUTINE 
TO  BUFFER  IF  APPROPRIATE 


/IS  READ  FOR  PORT  BEING  TRACED? 
/  NO,  JUST  PASS  IT  THROUGH 

/SAVE  CALLER'S  REGISTERS 

/SET  UP  DS  FOR  OUR  PROGRAM 


/FAKE  INT  14H  CALL 

/PASS  REQUEST  ON  TO  BIOS 
/VALID  READ? 

/  NO,  SKIP  BUFFER  UPDATE 

/GET  ADDRESS  OF  NEXT  BUFFER  LOCATION 
/MARK  AS  RECEIVED  BYTE 
/SAVE  DATA  IN  BUFFER 
/INCREMENT  BUFFER  BYTE  COUNT 

/POINT  TO  NEXT  LOCATION 

/SAVE  NEW  POINTER 

/ZERO  INDICATES  BUFFER  HAS  WRAPPED 
/TURN  COLLECTION  OFF  -  BUFFER  FULL 
/RESTORE  CALLER'S  REGISTERS 


COMMSCOPE  ENDP 

Figure  18-11.  Continued. 
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SUBTTL  CONTROL  INTERRUPT  HANDLER 

PAGE 


;  *  * 

;  *  CONTROL  * 

;  *  THIS  ROUTINE  PROCESSES  CONTROL  REQUESTS.  * 

;  *  * 


•  :ic:ic4c4c:|c:(c4:4c4:3ic4E3ic3ic4c*4c3i(9|(iie9|c3i(4t4(9|e:)e3|(4c***3i(3ic4c3iE4e4:*4(3|c3i(4(4c3ic3ie9ie3ic**%4:**4i**:ic:ic4c4:4:4:4c3|c3|(*4e4«*** 


CONTROL  PROC 

NEAR 

CMP 

AH,00H 

?STOP  REQUEST? 

JNE 

CNTL_START 

NO,  CHECK  START 

PUSH 

DS 

?SAVE  REGISTERS 

PUSH 

BX 

PUSH 

CS 

?SET  DS  FOR  OUR  ROUTINE 

POP 

DS 

MOV 

STATUS, 0 

TURN  PROCESSING  OFF 

MOV 

BX,BUFPNTR 

PLACE  STOP  MARK  IN  BUFFER 

MOV 

[BX],BYTE  PTR  8 OH 

. 

MOV 

[BX+1],BYTE  PTR  OFFH 

. 

INC 

COUNT 

INCREMENT  COUNT 

INC 

COUNT 

POP 

BX 

RESTORE  REGISTERS 

POP 

DS 

JMP 

CONTROL_DONE 

CNTL_START : 

CMP 

AH,01H 

START  REQUEST? 

JNE 

CNTL-JIESUME 

NO,  CHECK  RESUME 

MOV 

CS:PORT,DL 

SAVE  PORT  TO  TRACE 

MOV 

CS:BUFPNTR, OFFSET  VECTOR-INIT  /RESET  BUFFER  TO  START 

MOV 

CS: COUNT, 0 

‘ZERO  COUNT 

MOV 

CS : STATUS, 1 

START  LOGGING 

JMP 

CONTROL-DONE 

CNTL_RESUME ; 

CMP 

AH,02H 

RESUME  REQUEST? 

JNE 

CNTL-STATUS 

NO,  CHECK  STATUS 

CMP 

CSiBUFPNTR, 0 

END  OF  BUFFER  CONDITION? 

JE 

CONTROL-DONE 

YES,  DO  NOTHING 

MOV 

CS:PORT,DL 

SAVE  PORT  TO  TRACE 

MOV 

CS; STATUS, 1 

START  LOGGING 

JMP 

CONTROL-DONE 

CNTL_STATUS : 

CMP 

AH, 03H 

RETURN  STATUS  REQUEST? 

JNE 

CONTROL-DONE 

NO,  ERROR  -  DO  NOTHING 

MOV 

CX,CS: COUNT 

RETURN  COUNT 

PUSH 

CS 

RETURN  SEGMENT  ADDR  OF  BUFFER 

POP 

DX 

MOV 

BX, OFFSET  VECTOR-INIT 

RETURN  OFFSET  ADDR  OF  BUFFER 

Figure  18-11.  Continued. 
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CONTROL_DONE : 

IRET 

CONTROL  ENDP 


SUBTTL  INITIALIZE  INTERRUPT  VECTORS 

PAGE 

.  ********5|!**S|55|t*5i!*******S|t********5|C*******3|£!»!J|£S|£Si«******H«***5t!*********5(!***** 


♦  * 

*  VECTOR_INIT  * 

*  THIS  PROCEDURE  INITIALIZES  THE  INTERRUPT  VECTORS  AND  THEN  * 

*  EXITS  VIA  THE  MS-DOS  TERMINATE-AND-STAY-RESIDENT  FUNCTION.  * 

*  A  BUFFER  OF  64K  IS  RETAINED.  THE  FIRST  AVAILABLE  BYTE  * 

*  IN  THE  BUFFER  IS  THE  OFFSET  OF  VECTOR_INIT.  * 

*  * 


EVEN 

VECTOR_INIT  PROC  NEAR 


/ASSURE  BUFFER  ON  EVEN  BOUNDARY 


GET  ADDRESS  OF  COMM  VECTOR  (INT  14H) 


MOV 

AH, 35H 

MOV 

AL, 14H 

INT 

21H 

SAVE  OLD 

COMM  INT  ADDRESS 

MOV 

WORD  PTR  OLD_COMM_INT,BX 

MOV 

AX,ES 

MOV 

WORD  PTR  OLD_COMM_INT[2] ,AX 

SET  UP  COMM  INT  TO  POINT  TO  OUR  ROUTINE 


MOV  DX, OFFSET  COMMSCOPE 

MOV  AH,25H 

MOV  AL,14H 

INT  21 H 


INSTALL  CONTROL  ROUTINE  INT 

MOV  DX, OFFSET  CONTROL 

MOV  AH,25H 

MOV  AL,COMMSCOPE_INT 

INT  21 H 


SET  LENGTH  TO  64K,  EXIT  AND  STAY  RESIDENT 


MOV  AX,3100H 
MOV  DX,1000H 
INT  21 H 


/TERM  AND  STAY  RES  COMMAND 
/64K  RESERVED 
/  DONE 


Figure  18-11.  Continued. 


(more) 
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VECTOR_INIT  ENDP 

CSEG  ENDS 

END  INITIALIZE 

Figure  18-11.  Continued. 

In  order  to  use  the  symbolic  debugging  features  of  SYMDEB,  a  symbol  file  must  be  built  in 
a  specific  format.  The  SYMDEB  utility  MAPSYM  performs  this  function,  using  the  contents 
of  the  .MAP  file  built  by  LINK.  MAPSYM  is  easy  to  use  because  it  has  only  two  parameters: 
the  .MAP  file  and  the  /L  switch  (which  triggers  verbose  mode).  The  symbol  table  for 
BADSCOP  is  built  as  follows: 

C>MAPSYM  BADSCOP  <Enter> 

This  operation  produces  a  symbol  file  called  BADSCOP.SYM. 

Armed  with  the  .SYM  file  and  the  usual  collection  of  listing  and  design  notes,  the  program¬ 
mer  can  begin  the  debugging  process  using  SYMDEB^ 

The  first  task  is  to  discover  if  the  BADSCOP  TSR  is  installing  correctly.  To  test  this,  run  the 
.COM  file  under  SYMDEB  by  typing 

C> SYMDEB  BADSCOP.SYM  BADSCOP.COM  <Enter> 

Note  the  order  in  which  operands  are  passed  to  SYMDEB — it  is  not  the  order  that 
would  be  expected.  All  switches  (none  were  used  here)  must  immediately  follow  the 
word  SYMDEB.  These  switches  must  be  followed  in  turn  by  the  fully  qualified  names  of 
any  symbol  files  (in  this  case,  BADSCOP.SYM).  Only  then  is  the  name  of  the  file  to  be 
debugged  given.  If  BADSCOP  expected  any  parameters  in  the  command  tail,  they  would 
be  last.  This  potential  need  for  command-tail  data  is  the  reason  the  name  of  the  file  to  be 
debugged  follows  the  name  of  the  symbol  file.  SYMDEB  knows  that  the  first  non-.SYM  file 
it  encounters  is  the  file  to  be  loaded;  the  parameters  that  follow  the  filename  may  be  of 
any  form  and  number. 

When  SYMDEB  begins,  it  displays 

Microsoft  (R)  Symbolic  Debug  Utility  Version  4.00 
Copyright  (C)  Microsoft  Corp  1984,  1985.  All  rights  reserved. 

Processor  is  [80286] 

The  debugger  identifies  itself  and  then  notes  the  type  of  CPU  it  is  running  on — in  this 
case,  an  Intel  80286.  The  Display  or  Modify  Registers  command,  R,  gives  the  same  display 
that  DEBUG  gives,  with  one  exception. 

-R  <Enter> 

AX=0000  BX=0000  CX=0133  DX=0000  SP=FFFE  BP=0000  SI=0000  DI=0000 

DS=1FD0  ES=1FD0  SS=1FD0  CS=1FD0  IP=0100  NV  UP  El  PL  NZ  NA  PO  NC 

CSEG: INITIALIZE: 

1FD0:0100  E90701  JMP  VECTOR_INIT 
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The  instruction  at  CS:IP,  JMP,  is  now  preceded  by  the  information  that  the  instruction  is 
at  label  INITIALIZE  within  segment  CSEG.  An  examination  of  Figure  18-11  shows  that  this 
is  indeed  the  case. 

To  check  that  all  the  symbols  requested  with  the  PUBLIC  statement  are  present,  use  the 
X?*  form  of  the  Examine  Symbol  Map  command. 

-X?*  <Enter> 

CSEG:  (IFDO) 

0100  INITIALIZE  0103  OLD_COMM_INT  0107  COUNT  0109  STATUS 

010A  PORT  01  OB  BUFPNTR  01 OD  COMMSCOPE  01 8F  CONTROL 

020A  VECTOR_INIT 

The  display  shows  that  the  value  of  CSEG  (IFDOH)  matches  the  current  value  of  CS.  The 
offset  values  shown  for  the  procedure  names  and  data  names  match  the  numbers  from  an 
assembled  listing.  Because  this  is  a  .COM  file,  there  is  only  one  segment.  If  there  had  been 
other  segments — a  data  segment,  for  instance — they  would  have  been  shown  with  their 
values  and  associated  labels  and  offsets. 

The  purpose  of  this  test  is  to  determine  whether  the  problems  this  program  is  having  are 
caused  by  an  incorrect  installation.  First,  use  the  Trace  Program  Execution  command,  T,  to 
trace  through  the  first  few  steps. 


-T7  <Enter> 


AX=0000 

BX=0000 

CX=0133 

DX=0000 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1FD0 

SS=1FD0 

CS=1FD0 

IP=020A 

NV  UP  El 

PL  NZ 

NA  PO  NC 

CSEG:VECTOR-INIT: 

1FD0:020A  B435 

MOV  AH,  35 

f 

•5’ 

AX=3500 

BX=0000 

CX=0133 

DX=0000 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1FD0 

SS=1FD0 

CS=1FD0 

IP=020C 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:020C  B014 

MOV  AL,  1  4 

AX=3514 

BX=0000 

CX=0133 

DX=0000 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1FD0 

SS=1FD0 

CS=1FD0 

IP=020E 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:020E  CD21 

INT  21  ; 

Get  Interrupt  Vector 

AX=3514 

BX=1375 

CX=0133 

DX=0000 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=0210 

NV  UP  El 

PL  NZ 

NA  PO  NC 

IFDO: 0210  891E0301  MOV  [OLD_COMM_INT] , BX  DS: 01 03=0000 


AX=3514 

BX=1375 

CX=01 33 

DX=0000 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=0214 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:0214 

1  8CC0 

MOV  AX,ES 

AX=1567 

BX=1375 

CX=0133 

DX=0000 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=0216 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:0216  A30501 

MOV  [OLD_ 

COMM_INT+02  (0105)] 

,AX 

DS:0105=0000 

AX=1567 

BX=1375 

CX=0133 

DX=0000 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=0219 

NV  UP  El 

PL  NZ 

NA  PO  NC 

IFDO: 021 9  BA0D01  MOV  DX,010D 

This  part  of  the  program  uses  Interrupt  21H  Function  35H  to  obtain  the  current  vector  for 
Interrupt  14H.  Note  that,  unlike  DEBUG,  SYMDEB  coasts  right  through  an  Interrupt  21H 
call  with  no  problems.  It  not  only  knows  enough  not  to  make  the  call  but  also  displays  the 
type  of  function  call  being  made,  based  on  the  value  in  AH. 
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To  make  sure  that  the  correct  vector  for  the  old  Interrupt  14H  handler  has  been  stored,  use 
the  Display  Doublewords  command,  DD,  in  conjunction  with  a  symbol  name. 

-DD  OLD_COMM_INT  LI  <Enter> 

1FD0:01030  1567:1375 

This  is  the  correct  vector  address  (1567:1375H).  Now  trace  through  the  next  part  of  the 
program,  which  establishes  the  new  vectors  for  interrupts. 


-T8  <Enter> 


AX=1 567 

BX=1375 

CX=0133 

DX=010D 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1 567 

SS=1FD0 

CS=1FD0 

IP=021C 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:021C  B425 

MOV  AH, 25 

; 

AX=2567 

BX=1375 

CX=0133 

DX=010D 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=021E 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:021E  B014 

MOV  AL, 1 4 

AX=2514 

BX=1375 

CX=0133 

DX=010D 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=0220 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:0220  CD21 

INT  21  ; : 

Set  Vector 

AX=2514 

BX=1 375 

CX=0133 

DX=010D 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=0222 

NV  UP  El 

PL  NZ 

NA  P0‘  NC 

1FD0:0222 

!  BA8F01 

MOV  DX, 018F 

AX=2514 

BX=1375 

CX=0133 

DX=018F 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=0225 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:0225  B425 

MOV  AH, 25 

9 

AX=2514 

BX=1375 

CX=0133 

DX=018F 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=0227 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:0221 

'  B060 

MOV  AL, 60 

; 

t  \  t 

AX=2560 

BX=1375 

CX=0133 

DX=018F 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=0229 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:0229  CD21 

INT  21  ; : 

Set  Vector 

AX=2560 

BX=1375 

CX=0133 

DX=018F 

SP=FFFE 

BP=0000 

SI=0000 

DI=0000 

DS=1FD0 

ES=1567 

SS=1FD0 

CS=1FD0 

IP=022B 

NV  UP  El 

PL  NZ 

NA  PO  NC 

1FD0:022B  B80031  MOV  AX, 31 00 

Examination  of  these  trace  steps  shows  that  all  went  normally.  The  new  Interrupt  14H 
vector  has  been  established  at  COMMSCOPE;  the  vector  for  the  new  Interrupt  60H  has  also 
been  correctly  installed.  Use  the  Go  command,  G,  to  allow  the  program  to  continue  to 
termination  and  then  use  the  Quit  command,  Q,  to  exit  SYMDEB. 

-G  <Enter> 

Program  terminated  and  stayed  resident  (0) 

-Q  <Enter> 

SYMDEB  displays  the  information  that  the  program  terminated  with  a  completion  code 
of  zero  and  stayed  resident.  This  is  as  it  should  be,  and  the  conclusion  is  that  the  installa¬ 
tion  portion  of  this  TSR  is  running  properly.  The  problem  must  be  in  the  real-time  execu¬ 
tion  of  the  program. 

Debugging  the  resident  portion  of  a  TSR  is  complicated  but  not  especially  difficult.  A  sim¬ 
ple  program  is  used  to  exercise  the  TSR,  and  it  is  this  program  that  is  debugged.  As  this 
driver  program  exercises  the  TSR,  the  tracing  process  continues  into  the  resident  routine. 
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Because  symbol  tables  exist  for  the  TSR,  symbolic  debugging  can  be  used  to  follow  its 
execution. 

The  driver  program  will  be  TESTCOMM,  shown  in  Figure  18-10.  To  make  the  program 
more  easily  usable  by  SYMDEB,  one  line  has  been  added  before  the  first  SEGMENT 
statement: 

PUBLIC  BEGIN, MAINLOOP, SENDCOMM, TESTCOMM 

Using  the  .MAP  file  produced  by  LINK,  the  MAPSYM  routine  creates  TESTCOMM.SYM. 
TESTCOMM  can  now  be  invoked  with  two  symbol  files: 

C>SYMDEB  TESTCOMM.SYM  BADSCOP . SYM  TESTCOMM.EXE  <Enter> 

SYMDEB  will  load  both  symbol  files  and  then  load  TESTCOMM.EXE.  Because  the  name  of 
the  TESTCOMM.SYM  file  matches  the  name  of  the  program  being  loaded,  SYMDEB  makes 
TESTCOMM.SYM  the  active  symbol  file. 

Use  the  Register  command  to  show  that  the  test  program  was  properly  loaded. 

“R  <Enter> 

AX=0000  BX=0000  CX=0133  DX=0000  SP=0100  BP=0000  SI=0000  DI=0000 

DS=38EE  ES=38EE  SS=38FE  CS=390E  IP=0000  NV  UP  El  PL  NZ  NA  PO  NC 

CSEG: BEGIN: 

390E:0000  IE  PUSH  DS 

Then  use  the  Examine  Symbol  Map  command  to  determine  whether  the  symbol  files 
were  loaded  correctly.  The  form  X*  lists  all  the  symbol  maps  and  their  segments;  the  form 
X?*  lists  all  the  symbols  for  the  current  symbol  map  and  segment. 

-X*  <Enter> 

[38FE  TESTCOMM] 

[390E  CSEG] 

0000  BADSCOP 

0000  CSEG 
-X?*  <Enter> 

CSEG:  (390E) 

0000  BEGIN  0004  MAINLOOP  0011  SENDCOMM  0018  TESTCOMM 

The  current  symbol  map  and  segment  are  shown  in  square  brackets.  The  symbol  map  for 
BADSCOP  is  also  present  but  not  selected.  Note  that  there  are  no  values  associated  with 
BADSCOP  in  the  listing  produced  by  the  X?*  command,  because  all  the  symbols  currently 
available  to  SYMDEB  are  shown  and  only  the  symbols  in  TESTCOMM’s  CSEG  are  available 
(that  is,  TESTCOMM.SYM  is  the  only  active  symbol  file). 

Recall  that  the  BADSCOP  TSR  loaded  normally  but  locked  the  system  up  at  the  first  attempt 
to  issue  an  Interrupt  14H.  This  behavior  indicates  that  the  problem  is  associated  with  an  In¬ 
terrupt  14H  call.  TESTCOMM  repeatedly  makes  the  system  fail,  but  which  of  the  Interrupt 
14H  calls  within  TESTCOMM  is  causing  the  trouble  is  not  known.  The  most  straightfor¬ 
ward  approach  would  be  to  put  a  breakpoint  just  before  each  Interrupt  14H  instruction. 

Use  the  Disassemble  (Unassemble)  command,  U,  to  find  the  location  of  all  Interrupt  14H 
calls. 
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-U  MAINLOOP  LI  9  <Enter> 
CSEGrMAINLOOP: 


390E:0004 

B406 

MOV 

AH,  06 

390E:0006 

B2FF 

MOV 

DL,FF 

390E:0008 

CD21 

INT 

21 

390E:000A 

740C 

JZ 

TESTCOMM 

390E:000C 

3C03 

CMP 

AL,03 

390E:000E 

7501 

JNZ 

SENDCOMM 

390E:0010 

CB 

RETF 

CSEG:SENDCOMM: 

390E:001 1 

B401 

MOV 

AH,  01 

390E:0013 

BAOOOO 

MOV 

DX, BADSCOP! CSEG 

390E:0016 

CD14 

INT 

14 

CSEG: TESTCOMM: 

390E:0018 

B403 

MOV 

AH,  03 

390E:001A 

BAOOOO 

MOV 

DX,  BADSCOP ! CSEG 

390E:001D 

GDI  4 

INT 

14 

390E:001F 

80E401 

AND 

AH,  01 

390E:0022 

74E0 

JZ 

MAINLOOP 

390E:0024 

B402 

MOV 

AH,  02 

390E:0026 

BAOOOO 

MOV 

DX, BADSCOP! CSEG 

390E:0029 

GDI  4 

INT 

14 

390E:002B 

B406 

MOV 

AH,  06 

390E:002D 

8  ADO 

MOV 

DL,AL 

390E:002F 

CD21 

INT 

21 

390E:0031 

EBD1 

JMP 

MAINLOOP 

The  Disassemble  request  starts  at  MAINLOOP  and  acts  on  the  next  25  (19H)  instructions. 
SYMDEB  displays  symbol  names  instead  of  numbers  whenever  it  can.  However,  it  does 
get  confused  from  time  to  time,  so  a  grain  of  salt  might  be  needed  when  reading  the  dis¬ 
assembly.  Notice,  for  instance,  the  MOV  DX,0  instructions  at  offsets  13H,  lAH,  and  26H. 
SYMDEB  has  decided  that  what  is  being  moved  is  not  zero,  but  BADSCOPICSEG.  (The ! 
identifies  a  mapname  in  the  same  way  a :  defines  a  segment.)  In  this  case,  SYMDEB 
searched  its  map  tables  for  an  address  of  zero  and  found  one  at  CSEG  in  BADSCOP.  This 
segment  has  the  address  of  zero  because  it  has  not  been  initialized. 

Ignoring  the  name  confusions,  the  disassembly  clearly  shows  the  three  INT 14H  instruc¬ 
tions  at  offsets  16H,  IDH,  and  29H.  Use  the  Set  Breakpoints  command,  BP,  to  set  a  sticky, 
or  permanent,  breakpoint  at  each  of  these  locations.  In  this  way,  any  Interrupt  14H  call 
issued  by  TESTCOMM  will  be  intercepted  before  it  executes.  Use  the  List  Breakpoints 
command,  BL,  to  verify  the  breakpoints. 

-BP  1 6  <Enter> 

-BP  1 D  <Enter> 

-BP  29  <Enter> 

-BL  <Enter> 

0  e  390E:0016  [CSEG : SENDCOMM+05  (0016)] 

1  e  390E:001D  [CSEG: TESTCOMM+05  (001D)] 

2  e  390E:0029  [CSEG: TESTCOMM+1 1  (0029)] 
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The  List  Breakpoints  command  shows  that  breakpoint  0  is  enabled  and  set  to 
SENDCOMM+05,  or  CS:0016H.  Likewise,  breakpoint  1  is  at  CSiOOlDH  and  breakpoint  2  is  at 
CS:0029H.  It  is  important  to  trap  on  an  Interrupt  14H  so  that  the  subsequent  actions  of  the 
Interrupt  14H  service  routine  can  be  traced.  Now  allow  the  program  to  execute  until  it 
encounters  a  breakpoint. 

-G  <Enter> 

AX=0300  BX=0000  CX=0133  DX=0000  SP=00FC  BP=0000  SI=0000  DI=0000 

DS=38EE  ES=38EE  SS=38FE  CS=390E  IP=001D  NV  UP  El  PL  ZR  NA  PE  NC 

390E:001D  GDI  4  INT  14  ;BR1 

The  first  Interrupt  14H  encountered  is  the  one  at  the  second  breakpoint,  breakpoint  1,  as 
can  be  seen  from  the  address  at  which  execution  broke.  Also,  SYMDEB  was  kind  enough 
to  include  the  comment  ;BR1  on  the  disassembled  line,  indicating  that  this  is  Break  Re¬ 
quest  1.  The  instruction  at  this  location  is  a  request  for  serial  port  status  (AH  =  3)  and  the 
registers  are  loaded  correctly.  Execution  can  now  be  passed  to  the  TSR  by  simply  exe¬ 
cuting  the  current  instruction.  (Remember  that  the  instruction  displayed  at  a  breakpoint 
has  not  yet  been  executed.) 

-T  <Enter> 

AX=0300  BX=0000  CX=0133  DX=0000  SP=00F6  BP=0000  SI=0000  DI=000.0 

DS=38EE  ES=38EE  SS=38FE  CS=1FD0  IP=010D  NV  UP  DI  PL  ZR  NA  PE  NC 

1FD0:010D  2EF606090101  TEST  Byte  Ptr  CS: [0109], 01  CS:0109=00 

The  single  Trace  command  has  moved  execution  into  the  TSR.  Note  that  the  Interrupt 
14H  has  changed  the  value  of  CS  and  jumped  to  location  lODH  off  the  new  CS.  This  loca¬ 
tion  contains  the  first  instruction  of  the  COMMSCOPE  procedure  in  the  TSR.  SYMDEB 
does  not  know  that  a  different  segment  is  being  executed  and  must  be  instructed  to  use  a 
different  map  table.  Use  the  Open  Symbol  Map  command,  XO,  to  do  this,  instructing 
SYMDEB  to  set  the  active  map  table  to  BADSCOP!. 

-XO  BADSCOP !  <Enter> 

-X?*  <Enter> 


CSEG;  (0000) 

0100  INITIALIZE  0103  OLD.COMM-INT  0107  COUNT  0109  STATUS 

010A  PORT  01  OB  BUFPNTR  01 OD  COMMSCOPE  018F  CONTROL 

020A  VECTOR_INIT 

The  X?*  command  shows  that  the  BADSCOP  symbols  are  now  the  current  map.  They  are 
not  usable,  however,  because  the  value  of  CSEG — zero — needs  to  be  changed  to  the  cur¬ 
rent  CS  register.  To  correct  this,  use  the  SYMDEB  Set  Symbol  Value  command,  2.  This 
command  can  set  any  symbol  in  the  current  map  table  to  any  value;  the  value  can  be  a 
number,  another  symbol,  or  the  contents  of  a  register.  In  this  case,  set  the  value  of  CSEG 
in  BADSCOP!  to  the  current  contents  of  the  CS  register. 

-Z  CSEG  CS  <Enter> 

-X*  <Enter> 

38FE  TESTCOMM 

390E  CSEG 
[0000  BADSCOP] 

[1FD0  CSEG] 
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The  X*  command  confirms  that  BADSCOP!  is  now  the  selected  symbol  map  and  that  the 
CSEG  within  it  has  the  value  IFDOH.  The  CSEG  segment  in  TESTCOMM  is  an  entirely  dif¬ 
ferent  entity  and  still  has  its  correct  value,  which  will  be  valid  when  the  TSR  returns. 

With  the  symbols  set,  the  debugging  can  begin  by  tracing  the  first  few  instructions.  Be¬ 
cause  COMMSCOPE  is  not  currently  active,  the  routine  should  quickly  pass  the  processing 
on  to  the  old  interrupt  handler. 


-T5  <Enter> 


AX=0300 

BX=0000 

CX=0133 

DX=0000 

SP=00F6 

BP=0000 

SI=0000 

DI=0000 

DS=38EE 

ES=38EE 

SS=38FE 

CS=1FD0 

IP=0113 

NV  UP  DI 

PL  ZR 

NA  PE  NC 

1FD0:0113  7476 

JZ  COMMSCOPE+7E  (01 8B) 

AX=0300 

BX=0000 

CX=0133 

DX=0000 

SP=00F6 

BP=0000 

SI=0000 

DI=0000 

DS=38EE 

ES=38EE 

SS=38FE 

CS=1FD0 

IP=018B 

NV  UP  DI 

PL  ZR 

NA  PE  NC 

1FD0:018B  FF2E0301 

JMP  FAR 

[0103] 

DS:0103=0000 

AX=0300 

BX=0000 

CX=0133 

DX=0000 

SP=00F6 

BP=0000 

SI=0000 

DI=0000 

DS=38EE 

ES=38EE 

SS=38FE 

cs=oooo 

IP=0000 

NV  UP  DI 

PL  ZR 

NA  PE  NC 

0000:0000  381E6715  CMP  [1567], BL 

DS: 1567=00 

AX=0300 

BX=0000 

CX=0133 

DX=0000 

SP=00F6 

BP=0000 

SI=0000 

DI=0000 

DS=38EE 

ES=38EE 

SS=38FE 

cs=oooo 

IP=0004 

NV  UP  DI 

PL  ZR 

NA  PE  NC 

0000:0004  BC2CE1 

MOV  SP,E12C 

AX=0300 

BX=0000 

CX=0133 

DX=0000 

SP=E12C 

BP=0000 

SI=0000 

DI=0000 

DS=38EE 

ES=38EE 

SS=38FE 

cs=oooo 

IP=0007 

NV  UP  DI 

PL  ZR 

NA  PE  NC 

0000:0007  2F  DAS 

STATUS  is  tested  with  a  mask  of  OlH  at  CSrOlODH;  the  test  sets  the  zero  flag,  indicating  that 
tracing  is  disabled.  The  JZ  to  COMMSCOPE+7E  (CS:018BH)  is  taken.  At  this  address  is  a  far 
jump  to  the  old  Interrupt  14H  handler  at  1567:1375H.  The  jump  is  taken  and  then  disaster 
strikes.  Instead  of  going  to  the  correct  address,  processing  is  suddenly  at  0000:0000H.  Any 
wild  jump  is  dangerous,  but  a  far  jump  into  low  memory  is  exceptionally  so.  This  explains 
the  system’s  locking  up  and  requiring  a  cold  boot  to  recover. 

Now  that  the  bug  has  been  caught  in  the  act,  it  should  be  a  simple  matter  to  determine 
what  went  wrong.  When  the  BADSCOP  TSR  installed  itself,  it  was  seen  to  place  the  correct 
offset  address  at  0103H.  Yet  whenever  the  resident  portion  of  the  TSR  tries  to  use  the  value 
at  that  address,  it  finds  all  zeros.  The  initialization  routine  placed  the  address  at  the  symbol 
OLD^COMM^JNT  (1FD0:0103H).  If  that  location  is  examined,  the  following  is  found: 

-DD  OLD_COMM_INT  Li  <Enter> 

1FD0:0103  1567:1375 

This  is  the  correct  address.  Why,  then,  did  the  programs  find  zero  there?  Use  the  Display 
Doublewords  command  to  look  at  the  same  memory  location  again,  this  time  using  the 
specific  address  0103H  rather  than  a  program  symbol. 

-DD  103  LI  <Enter> 

38EE:0103  0000:0000 

The  dump  of  OLD_COMM_INT  looked  at  1FD0:0103H,  but  the  simple  dump  looked  at 
38EE:0103H.  The  explanation  is  clear  when  the  values  of  the  registers  just  before  the  far 
jump  are  examined.  The  CS  register  contains  IFDOH  and  the  DS  register  contains  38EEH. 
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This  is  the  problem — there  is  a  missing  CS  override  on  the  indirect  jump  command. 

When  the  TSR  installed  itself,  CS  and  DS  were  the  same  because  it  was  a  .COM  file.  When 
the  TSR  is  entered  as  the  result  of  an  interrupt  call,  only  CS  is  set;  DS  remains  what  it  was 
in  the  calling  program.  Without  an  override,  the  CPU  assumed  that  the  address  of  the  desti¬ 
nation  of  the  far  call  was  located  at  offset  103H  from  the  DS  register.  This  offset,  unfortu¬ 
nately,  contained  zeros,  and  the  program  locked  up  the  system. 

The  problem  is  now  easily  corrected.  Exit  SYMDEB  with  the  Quit  command  and  edit  the 
program  source  so  that  the  offending  line  reads 

OLD_JUMP : 

JMP  CS : OLD_COMM_INT 

Debugging  C  programs  with  SYMDEB 

One  of  SYMDEB’s  finest  features  is  the  ability  to  debug  with  source-line  data  from  pro¬ 
grams  written  in  Microsoft  C,  Pascal,  and  FORTRAN.  The  actual  lines  of  C  or  FORTRAN 
can  be  included  in  the  debugging  display,  and  the  addresses  for  breakpoints  show  which 
line  of  code  the  breakpoints  are  in.  Combined  with  symbolic  debugging,  these  features 
provide  a  powerful  tool  that  can  significantly  reduce  debugging  time  for  programs 
written  in  a  supported  language. 

The  following  rather  complicated  case  illustrates  SYMDEB  at  its  best.  The  program 
BADSCOP  from  the  previous  example  was  not  completely  debugged.  Although  the  patch 
to  the  BADSCOP  code  at  OLD^JUMP:  did  correct  the  disastrous  problem  that  caused  the 
system  to  lock  up,  running  the  program  in  a  realistic  test  situation  reveals  that  a  subtle 
problem  still  remains  that  might  be  in  either  BADSCOP  or  one  of  the  support  programs. 

Before  we  investigate  the  problem,  a  quick  review  of  the  programs  in  the  COMMSCOP 
system  is  in  order.  At  the  heart  of  the  system  is  the  Interrupt  14H  intercept  program 
COMMSCOP.  When  executed,  this  program  installs  itself  as  a  TSR  and  intercepts  all  Inter¬ 
rupt  14H  calls.  (The  incorrect  version  of  the  COMMSCOP  program  is  called  BADSCOP.) 
The  installed  COMMSCOP  TSR  passes  all  Interrupt  14H  calls  on  to  the  real  service  routine 
in  the  ROM  BIOS  until  it  is  commanded  to  start  tracing.  The  COMMSCMD  routine  controls 
tracing.  This  control  routine  can  request  that  COMMSCOP  start,  stop,  or  resume  tracing  for 
a  specific  serial  port.  These  commands  are  facilitated  through  Interrupt  60H,  which  is 
recognized  by  the  COMMSCOP  TSR  as  a  command  request.  When  tracing  is  started,  the 
trace  buffer  is  emptied  by  zeroing  the  trace  count  and  setting  the  buffer  pointer  to  the  first 
buffer  location.  When  tracing  is  stopped  by  COMMSCMD’s  STOP  command,  a  marker  is 
placed  in  the  buffer  to  indicate  the  end  of  a  trace  segment.  Tracing  can  be  resumed  with 
COMMSCMD’s  RESUME  command.  Resuming  a  trace  preserves  collected  data  and  places 
new  trace  data  after  the  marker  in  the  trace  buffer.  The  RESUME  command  differs  from 
the  START  command  in  that  the  buffer  is  not  emptied. 

Now  the  problem:  When  the  serial  data  tracing  is  started  with  COMMSCMD  (^see  Figure 
18-5),  data  is  collected  normally.  When  COMMSCMD  issues  a  STOP  command  and  the 
data  is  displayed  with  COMMDUMP  {see  Figure  18-7),  the  data  appears  normal.  The 
traced  data  ends  with  a  stop  mark  just  as  it  should.  However,  the  RESUME  command  of 
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COMMSCMD  causes  the  stop  mark  to  be  overwritten  with  collected  data.  After  this,  when¬ 
ever  COMMDUMP  displays  data  an  extra  byte  appears  at  the  end  of  the  data.  The  problem 
could  be  with  either  BADSCOP  or  COMMSCMD.  SYMDEB  has  the  facilities  to  debug  both 
the  routines  at  once. 

The  first  step  in  the  debugging  process  is,  as  usual,  to  gather  all  the  listings  and  design 
documentation.  As  a  part  of  this  process,  the  symbol  tables  needed  for  SYMDEB  must  be 
prepared.  The  process  of  preparing  a  symbol  table  for  BADSCOP  has  already  been  ex¬ 
plained;  however,  preparing  the  SYMDEB  input  and  supporting  listings  for  a  C  program  is 
slightly  more  complicated. 

First,  when  the  C  program  is  compiled,  three  switches  must  be  specified.  (C  switches  are 
case  sensitive  and  must  be  entered  exactly  as  shown.) 

C>MSC  /Fc  /Zd  /Od  COMMSCMD;  <Enter> 

The  /Zd  switch  produces  an  object  file  containing  line-number  information  that  corre¬ 
sponds  to  the  line  numbers  of  the  source  file.  The  /Od  switch  disables  optimization  that 
involves  complex  code  rearrangement;  localized  optimization,  peephole  optimization,  and 
other  simple  forms  of  optimization  are  still  performed.  The  /Od  switch  is  not  required,  but 
code  rearrangement  can  make  the  resulting  object  code  more  difficult  to  debug. 

The  /Fc  switch  invokes  a  feature  of  C  that  is  especially  important  for  debugging  with 
SYMDEB:  a  listing  that  contains  the  C  source  lines  and  the  generated  assembler  code  inter¬ 
mixed.  The  file  is  a  .COD  file;  the  command  line  shown  above  would  produce  the  file 
COMMSCMD.COD.  Figure  18-12  shows  the  contents  of  COMMSCMD.COD. 


;  Static  Name  Aliases 

;  $S1 42_commands  EQU  commands 

TITLE  commscmd 
;  NAME  commscmd. C 

.287 

-TEXT  SEGMENT  BYTE  PUBLIC  ’CODE' 

-TEXT  ENDS 

-DATA  SEGMENT  WORD  PUBLIC  'DATA' 

-DATA  ENDS 

CONST  SEGMENT  WORD  PUBLIC  'CONST' 

CONST  ENDS 

-BSS  SEGMENT  WORD  PUBLIC  ' BSS ' 

-BSS  ENDS 

DGROUP  GROUP  CONST,  -BSS,  -DATA 

ASSUME  CS:  -TEXT,  DS :  DGROUP,  SS:  DGROUP, 
EXTRN  _int86:NEAR 

EXTRN  -print f: NEAR 

EXTRN  -StricmprNEAR 

EXTRN  -atoi:NEAR 

EXTRN  _ chkstk : NEAR 

-DATA  SEGMENT 

Figure  18-12.  COMMSCMD.COD. 


ES:  DGROUP 
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;!***  char  *argv[]; 

;  ;  *  *  *  { 

;  Line  31 
;  argc  =  4 

;  argv  =  6 

;  cmd  =  -4 

;  port  =  -6 

;  result  =  -2 

;  inregs  =  -34 

;  outregs  =  -20 

;!***  int  cmd,  port,  result; 

static  char  commands[31  [10]  =  {"STOPPED",  "STARTED",  "RESUMED"}; 

;!***  union  REGS  inregs,  outregs; 

;  j  *** 

; ; *  *  *  cmd  =  0 ; 

;  Line  36 

***  00000b  cl  46  fc  00  00  mov  WORD  PTR  [bp-4],0  ;cmd 

;;***  port  =  0; 

;  Line  37 

***  000010  cl  46  fa  00  00  mov  WORD  PTR  [bp-6],0  ;port 

;  ;  *** 

;  !***  if  (argc  >  1 ) 

;  Line  39 


*** 

000015 

83 

7e 

04  01 

cmp 

WORD  PTR  [bp+4],l 

;  argc 

000019 

It 

03 

jg 

$JCC25 

*** 

00001b 

e9 

5d 

00 

jmp 

$1145 

$JCC25; 

;!***  { 

;  Line  40 

;!***  if  (0  ==  stricmp (argv[l ] ,  "STOP")) 

;  Line  41 


*** 

OOOOle 

b8 

00 

00 

mov 

ax, OFFSET 

DGROUP:$SGl 48 

*** 

000021 

50 

push 

ax 

000022 

8b 

5e 

06 

mov 

bx, [bp+6] 

;  argv 

*** 

000025 

ff 

77 

02 

push 

WORD  PTR 

[bx+2] 

**  * 

000028 

e8 

00 

00 

call 

_stricmp 

*** 

00002b 

83 

c4 

04 

add 

sp,  4 

00002e 

3d 

00 

00 

cmp 

ax,  0 

*** 

000031 

74 

03 

je 

$JCC49 

*** 

000033 

e9 

08 

00 

jmp 

$1147 

$JCC49: 

;  ! *  *  *  cmd  =  0 ; 

;  Line  42 

***  000036  cl  46  fc  00  00  mov  WORD  PTR  [bp-4],0  ; cmd 

;[***  else  if  (0  ==  stricmp (argv [ 1 ) ,  "START")) 

Figure  18-12.  Continued.  (more) 
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;  Line 

51 

***  000084 

8b  5e  06 

mov 

bx, [bp+6] 

;  argv 

***  000087 

ff  77  04 

push 

WORD  PTR  [bx+4] 

***  00008a 

e8  00  00 

call 

_atoi 

***  00008d 

83  c4  02 

add 

sp,2 

***  000090 

89  46  fa 

mov 

[bp-6] , ax 

;  port 

;  [  *  *  * 

if  (port 

>  0) 

;  Line 

52 

***  000093 

83  7e  fa 

00 

cmp 

WORD  PTR  [bp-6 1,0 

;port 

***  000097 

If  03 

jg 

$JCC1 51 

***  000099 

e9  03  00 

$JCC151 : 

jmp 

$1156 

;  [  *  *  * 

port  =  port-1 

; 

;  Line 

53 

***  00009c 

ff  4e  fa 

dec 

WORD  PTR  [bp- 6] 

;  port 

;  1  *  *  ♦ 

} 

;  Line 

54 

$1156: 

;  j  ♦  *  * 

;  1  *  *  * 

inregs .h. 

ah 

=  cmd; 

;  Line 

56 

$1155: 

***  00009f 

8a  46  fc 

mov 

al, [bp-4] 

;  cmd 

***  0000a2 

88  46  df 

mov 

[bp-33] ,al 

;  !  *  *  * 

inregs . x 

dx 

=  port; 

;  Line 

57 

***  0000a5 

8b  46  fa 

mov 

ax, [bp-6] 

;port 

0000a8 

89  46  e4 

mov 

[bp-28], ax 

;  J  *  ♦  * 

result  = 

int86 (COMMCMD 

,  Sinregs,  Soutregs) ; 

;  Line 

58 

OOOOab 

8d  46  ec 

lea 

ax, [bp-20] 

;outregs 

***  OOOOae 

50 

push 

ax 

***  OOOOaf 

8d  46  de 

lea 

ax, [bp-34] 

; inregs  I 

***  0000b2 

50 

push 

ax 

1 

***  0000b3 

b8  60  00 

mov 

ax,  96 

***  OOOObe 

50 

push 

ax 

***  0000b7 

e8  00  00 

call 

_int86 

***  OOOOba 

83  c4  06 

add 

sp,  6 

***  OOOObd 

89  46  fe 

mov 

[bp-2] ,ax 

; result 

;  j  *  *  * 

;  j  *  *  * 

;  j  *  *  * 

print f  (''\nCorranunicat ions  tracing  %s 

for  port 

COM%1d:\n", 

;  [  *  ♦  * 

commands [cmd] , 

port  +  1 ) ; 

;  Line 

62 

***  OOOOcO 

8b  46  fa 

mov 

ax, [bp-6] 

;  port 

***  0000c3 

40 

inc 

ax 

***  0000c4 

50 

push 

ax 

***  0000c5 

8b  46  fc 

mov 

ax, [bp-4] 

;  cmd 

***  0000c8 

8b  c8 

mov 

cx,  ax 

***  OOOOca 

d1  eO 

shl 

ax,  1 

OOOOcc 

d1  eO 

shl 

ax,  1 

***  OOOOce 

03  cl 

add 

ax,  cx 

***  OOOOdO 

d1  eO 

shl 

ax,  1 

Figure  18-12.  Continued. 


(more) 
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*** 

0000d2 

05 

40 

00 

add 

ax, OFFSET 

DGROUP  :  $S1  42— commands 

*** 

OOOOdS 

50 

push 

ax 

0000d6 

b8 

12 

00 

mov 

ax, OFFSET 

DGROUP:$SG157 

*** 

0000d9 

50 

push 

ax 

OOOOda 

e8 

00 

00 

call 

— print f 

*** 

OOOOdd 

83 

c4 

06 

add 

sp,  6 

63 

$EX138: 

*** 

OOOOeO 

5e 

pop 

si 

*** 

OOOOel 

5f 

pop 

di 

sk  4c  4c 

0000e2 

8b 

e5 

mov 

sp,bp 

4:4c  4c 

0000e4 

5d 

pop 

bp 

4c  4c  4c 

OOOOeS 

c3 

ret 

—main  ENDP 

-TEXT  ENDS 

END 

Figure  18-12.  Continued. 

After  the  C  program  is  compiled,  it  must  be  linked  using  the  /LI  switch  to  indicate  that  the 
line  number  information  is  to  be  maintained: 

OLINK  COMMSCMD  /MAP  /LI;  <Enter> 

The  /MAP  switch  is  still  required  to  generate  a  map  file  of  public  names  for  use  in  building 
the  symbol  file,  which  is  created  in  the  usual  manner: 

OMAPSYM  COMMSCMD  <Enter> 

Everything  needed  to  debug  COMMSCMD  and  BADSCOP  is  now  available.  The  first  test  is 
an  attempt  to  start  tracing.  To  invoke  SYMDEB,  type 

OSYMDEB  COMMSCMD. SYM  BADSCOP . SYM  COMMSCMD.EXE  START  1  <Enter> 

SYMDEB  first  loads  the  symbol  files  for  COMMSCMD  and  BADSCOP  and  then  loads  the 
.EXE  file  for  COMMSCMD.  BADSCOP  is  already  in  memory,  having  been  loaded  by  simply 
running  it.  (It  then  stays  resident.)  The  last  two  entries  in  the  command  line  load  the  com¬ 
mand  tail  for  COMMSCMD  with  a  start  request  for  COMl.  SYMDEB  responds  with 

Microsoft  (R)  Symbolic  Debug  Utility  Version  4.00 
Copyright  (C)  Microsoft  Corp  1984,  1985.  All  rights  reserved. 

Processor  is  [80286] 

Use  the  Register  and  Examine  Symbol  Map  commands  to  display  the  initial  register  values 
and  symbol  table  information. 
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-R  <Enter> 


AX=0000  BX=0000 

CX=1928  DX=0000 

SP=0800  BP=0000 

SI=0000  DI=0000 

DS=2CA0  ES=2CA0 

SS=2E85  CS=2CB0 

IP=010F  NV  UP  El 

PL  NZ  NA  PO  NC 

-TEXT: _ astart: 

2CB0:010F  B430 

-X*  <Enter> 

[2CB0  COMMSCMD] 

[2CB0  -TEXT] 

2E08  DGROUP 

0000  BADSCOP 

0000  CSEG 

-X?*  <Enter> 

9876  _ acrtused 

-TEXT:  (2CB0) 

0010  —main 

00F9  _ chkstk 

MOV  AH, 30 

9876  _ acrtmsg 

00F6  — atoi 

01  OF  _ astart 

01 AB 

_ cintDIV 

;  'O' 

01AE  amsg— exit 

01B9  -int86 

023A  — printf 

0270 

— strcmpi 

0270  — stricmp 

02C2  _ stbuf 

0361  _ ftbuf 

03E7 

_ catox 

043C  _ nullcheck 

0458  _ cinit 

0507  -exit 

051E 

_ exit 

054A  _ ctermsub 

0572  _ dosretO 

057A  _ dosretax 

0586 

_ maperror 

05BA  _ NMSG-TEXT 

05EA  _ NMSG-WRITE 

0613  _ output 

0E22 

_ setargv 

0F07  _ setenvp 

0F6D  _ flsbuf 

1098  _ fassign 

1098 

_ cropzeros 

1098  _ ^positive 

1098  _ forcdecpt 

1098  _ cfltcvt 

109B 

-fflush 

1 1 03  — isatty 

1 1 25  _ myalloc 

1 1 67  — strlen 

1182 

— ultoa 

1 1  8C  _ fptrap 

1192  -flushall 

11C3  -free 

11C3 

_ nfree 

11D1  -malloc 

11D1  _ nmalloc 

1217  —write 

12F1 

_ cltoasub 

12FD  _ cxtoa 

1351  _ amalloc 

1432  _ amexpand 

146C 

_ ami ink 

148E  _ amallocbrk 

1 4AD  — brkctl 

DGROUP:  (2E08) 

0094  STKHQQ 

0096  _ asizds 

0098 

_ atopsp 

009A  _ abrktb 

OOEA  _ abrktbe 

OOEA 

_ abrkp 

OOEC  _ iob 

01  8C  _iob2 

0204  _ lastiob 

0212 

_ aintdiv 

021  6  _ fac 

021 E  — errno 

0220  _ umaskval 

0222 

— ^pspadr 

0224  _ ^psp 

0226  _ osmajor 

0226  _ dosvermajor  0227 

_ osminor 

0227  _ dosverminor 

0228  _ oserr 

0228  _ doserrno 

022A 

_ osfile 

02 3E  _ argc 

0240  _ argv 

0242  —environ 

0244 

_ child 

0246  _ csigtab 

0278  _ cflush 

027A  _ asegds 

0286 

_ asegl 

0288  _ asegn 

028A  _ asegr 

028C  _ amblksiz 

0292 

_ fpinit 

03A8  — edata 

03D0  _ bufout 

05D0  _ bufin 

07D0 

—end 

The  Register  command  shows  that  the  first  instruction  to  be  executed  will  be  at  symbol 

_ astart  in  the  _TEXT  segment.  (Note  that  C  puts  a  single  underscore  in  front  of  all  public 

library  and  routine  names;  a  double  underscore  indicates  routines  for  C’s  internal  use.)  The 
Examine  Symbol  Map  command  reveals  that  the  symbol  map  COMMSCMD!  has  two  seg¬ 
ments,  ^TEXT  and  DGROUP,  with  _TEXT  currently  selected.  The  segment  in  BADSCOP!, 
CSEG,  has  no  value  assigned  to  it  because  SYMDEB  doesn’t  know  where  it  is;  one  of  the 
debugging  tasks  is  to  determine  the  location  of  CSEG. 

C  places  initialization  and  preamble  code  at  the  front  of  its  object  modules.  This  code  can 
be  skipped  during  debugging,  so  this  example  begins  at  the  label  ^main.  Examination  of 
the  code  at  this  label  using  the  Disassemble  command  reveals  the  following: 
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-U  —main  <Enter> 
commscmd.C 
29:  int  argc; 

—TEXT: —main: 


2CB0:0010  55 

PUSH 

BP 

2CB0:0011  8BEC 

MOV 

BP,SP 

2CB0:0013  B82200 

MOV 

AX, 0022 

2CB0:0016  E8E000 

CALL 

_ chkstk 

2CB0:0019  57 

PUSH 

DI 

This  disassembly  shows  the  way  source-line  information  is  displayed.  These  instructions 
are  generated  by  line  29  of  COMMSCMD.C.  When  the  disassembly  is  compared  with  the 
listing  in  Figure  18-12,  the  same  instructions  are  seen.  However,  their  addresses  are  differ¬ 
ent.  The  addresses  in  the  disassembly  are  relative  to  the  start  of  the  segment  ^TEXT,  but 
the  addresses  in  the  listing  are  relative  to  the  start  of  ^main.  SYMDEB  allows  address  ref¬ 
erences  to  be  made  relative  to  a  symbol,  so  breakpoints  can  be  set  as  displacements  from 
^main  and  the  addresses  shown  in  the  listing  can  be  used. 

Because  the  location  of  the  problem  being  debugged  is  not  known,  breakpoints  must  be 
placed  strategically  throughout  COMMSCMD  to  trace  the  execution  of  the  program.  Use 
the  Set  Breakpoints  command  to  set  the  breakpoints. 

-BP  ^ain+1e  <Enter> 

-BP  -main+36  <Enter> 

-BP  _main+56  <Enter> 

-BP  _main+76  <Enter> 

-BP  — main+7b  <Enter> 

-BP  _main+9c  <Enter> 

-BP  — main+b7  <Enter> 

-BP  _main+e5  <Enter> 

-BL  <Enter> 

0  e  2CB0:002E  [-TEXT :-main+1 E  [002E) ]  commscmd.C: 41 

1  e  2CB0:0046  [-TEXT : -main+36  (0046)]  commscmd.C: 42 

2  e  2CB0:0066  [— TEXT:— main+56  (0066)]  commscmd.C: 44 

3  e  2CB0:0086  [-TEXT:-main+76  (0086)]  commscmd.C: 46 

4  e  2CB0:008B  [-TEXT :-main+7B  (008B) ]  commscmd.C : 49 

5  e  2CB0:00AC  [-TEXT :-main+9C  (OOAC) ]  commscmd.C : 53 

6  e  2CB0:00C7  [-TEXT : -main +B 7  (00C7) ]  commscmd.C : 58 

7  e  2CB0:00F5  [-TEXT : -main +E 5  (00F5) ]  commscmd. C : 63 

The  List  Breakpoints  command  shows  the  breakpoint  addresses  in  three  ways:  first  the 
absolute  segmentioffset  address,  then  the  displacement  from  the  label  and  finally 

the  line  number  in  COMMSCMD.C. 

The  first  part  of  the  COMMSCMD  program  decodes  the  arguments  and  sets  the  appro¬ 
priate  values  for  cmd  and  port.  If  there  are  no  arguments,  this  decoding  is  skipped;  if  there 
are  arguments,  the  decoding  begins  at  line  41,  so  the  first  breakpoint  is  set  there.  If  the  cri¬ 
terion  of  line  41  is  met  (the  first  argument  is  STOP),  then  line  42  is  executed.  The  second 
breakpoint  is  set  there.  Reaching  the  second  breakpoint  means  that  a  STOP  command  was 
properly  decoded.  If  the  command  was  not  STOP,  execution  continues  at  line  43.  If  this 
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test  is  passed,  line  44  is  executed.  This  is  the  location  of  the  third  breakpoint.  If  the  test  at 
line  44  fails  but  the  one  at  line  45  is  passed,  then  the  breakpoint  at  line  46  is  executed. 
Whether  or  not  one  of  the  tests  passes,  execution  ends  up  at  line  49.  At  this  point,  the  pro¬ 
gram  tests  for  the  presence  of  a  second  operand.  If  there  is  a  second  operand,  execution 
traps  at  line  53,  where  the  program  decrements  the  port  number  to  put  it  in  the  proper 
form  for  the  Interrupt  60H  handler.  Execution  will  then  always  stop  in  line  58,  just  before 
the  call  to  _^int86.  C_int86  is  a  library  routine  that  loads  registers  and  executes  INT 
instructions.) 

When  the  program  is  run  with  START  1  in  the  command  tail,  it  gives  the  following  results: 


-G  <Enter> 

AX=0022  BX=0F82  CX=0019  DX=0098  SP=0F7E  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=002E  NV  UP  El  PL  NZ  NA  PO  NC 

41:  if  (0  ==  stricmp (argv[1 ] , "STOP”) ) 

2CB0:002E  B83600  MOV  AX, 0036  ;BR0 

-G  <Enter> 

AX=0000  BX=415A  CX=0000  DX=0098  SP=0F7E  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=0066  NV  UP  El  PL  ZR  NA  PE  NC 


4  4  :  cmd  =  1 ; 

2CB0:0066  C746FC0100  MOV  Word  Ptr  [BP-04), 0001  ;BR2  SS:0FA0=0000 

-G  <Enter> 

AX=0000  BX=415A  CX=0000  DX=0098  SP=0F7E  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=008B  NV  UP  El  PL  ZR  NA  PE  NC 


49;  if  (argc  ==  3) 

2CB0;008B  837E0403  CMP 

-G  <Enter> 

AX=0001  BX=00D0  CX=0000  DX=0000 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0 

5  port  =  port-1 ; 

2CB0:00AC  FF4EFA  DEC 

-G  <Enter> 

AX=0060  BX=00D0  CX=0000  DX=0000 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0 

2CB0;00C7  E8EF00  CALL 


Word  Ptr  [BP+04],+03  ;BR4  SS;0FA8=0003 

SP=0F7E  BP=0FA4  SI=0089  DI=1065 

IP=00AC  NV  UP  El  PL  NZ  NA  PO  NC 

Word  Ptr  [BP-06]  ;BR5  SS:0F9E=0001 

SP=0F78  BP=0FA4  SI=0089  DI=1065 

IP=00C7  NV  UP  El  PL  ZR  NA  PE  NC 
_int86  ;BR6 


The  first  break  occurs  at  line  41,  indicating  that  one  or  more  arguments  were  present  in 
the  command  line.  The  next  break  is  at  line  44,  where  the  program  sets  the  cmd  code  for 
Interrupt  60H  to  1,  the  correct  value  for  a  start  request.  The  next  break  occurs  at  line  49, 
where  the  program  checks  the  number  of  arguments.  If  this  number  is  3,  then  there  is  a 
second  argument  in  the  command  line.  (Remember  that,  in  C,  the  first  argument  is  the 
name  of  the  routine,  so  an  argument  count  of  3  actually  means  that  there  are  2  arguments 
present.)  The  number  of  arguments  is  at  BP+04,  or  SS:0FA8H,  and  it  is  indeed  3.  Therefore, 
the  next  break  is  at  line  53.  The  program  decrements  the  current  value  of  port,  leaving  a 
value  of  0,  which  is  what  Interrupt  60H  expects  to  see  for  COMl. 

Continuing  execution  causes  a  break  just  before  the  call  to  _  int86.  To  validate  that 
the  Interrupt  60H  call  is  being  made  correctly,  set  a  breakpoint  just  before  the  INT  60H 
instruction  is  issued.  Unfortunately,  no  listing  of  _int86  is  available,  so  no  alternative 
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exists  but  to  trace  the  execution  of  the  routine  until  the  INT  instruction  is  issued.  The 
details  of  the  processing  are  of  no  interest  to  this  debugging  session,  so  they  can  be 
ignored  until  an  INT  60H  is  seen.  (The  trace  offers  a  great  deal  of  information  about  how  C 
interfaces  with  subroutines.  Studying  the  trace  would  be  educational  but  is  beyond  the 
scope  of  this  example.) 

-T  5  <Enter> 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F76  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01B9  NV  UP  El  PL  ZR  NA  PE  NC 

_TEXT:_int86: 

2CB0:01B9  55  PUSH  BP 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F74  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01BA  NV  UP  El  PL  ZR  NA  PE  NC 

2CB0:01BA  8BEC  MOV  BP,SP 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F74  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01BC  NV  UP  El  PL  ZR  NA  PE  NC 

2CB0:01BC  56  PUSH  SI 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F72  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01BD  NV  UP  El  PL  ZR  NA  PE  NC 

2CB0:01BD  57  PUSH  DI 

AX=0060  BX=00D0  CX=0000  DX=0000  ;SP=0F70  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01BE  NV  UP  El  PL  ZR  NA  PE  NC 

2CB0:01BE  83EC0A  SUB  SP,+0A 

-T  5  <Enter> 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01C1  NV  UP  El  PL  NZ  AC  PE  NC 

2CB0:01C1  C646F6CD  MOV  Byte  Ptr  [BP-0A],CD  SS:0F6A=BE 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01C5  NV  UP  El  PL  NZ  AC  PE  NC 

2CB0:01C5  8B4604  MOV  AX, [BP+04]  SS:0F78=0060 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01C8  NV  UP  El  PL  NZ  AC  PE  NC 

2CB0:01C8  8846F7  MOV  [BP-09], AL  SS:0F6B=01 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01CB  NV  UP  El  PL  NZ  AC  PE  NC 

2CB0:01CB  3C25  CMP  AL,25 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01CD  NV  UP  El  PL  NZ  AC  PO  NC 

2CB0:01CD  740A  JZ  _int86+20  (01D9) 

-T  5  <Enter> 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01CF  NV  UP  El  PL  NZ  AC  PO  NC 

2CB0:01CF  3C26  CMP  AL,26 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01D1  NV  UP  El  PL  NZ  AC  PE  NC 

2CB0:01D1  7406  JZ  _int86+20  (01D9) 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01D3  NV  UP  El  PL  NZ  AC  PE  NC 

2CB0:01D3  C646F8CB  MOV  Byte  Ptr  [BP-08], CB  SS:0F6C=B0 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=01D7  NV  UP  El  PL  NZ  AC  PE  NC 

(more) 
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2CB0:01D7  EBOC 
AX=0060  BX=00D0 

DS=2E08  ES=2E08 

2CB0:01E5  8C56F4 
-T  5  <Enter> 
AX=0060  BX=00D0 

DS=2E08  ES=2E08 

2CB0:01E8  8D46F6 
AX=0F6A  BX=00D0 
DS=2E08  ES=2E08 

2CB0:01EB  8946F2 
AX=0F6A  BX=00D0 
DS=2E08  ES=2E08 

2CB0:01EE  8B7E06 
AX=0F6A  BX=00D0 
DS=2E08  ES=2E08 

2CB0:01F1  8B05 
AX=0100  BX=00D0 

DS=2E08  ES=2E08 

2CB0:01F3  8B5D02 
-T  5  <Enter> 
AX=0100  BX=0000 

DS=2E08  ES=2E08 

2CB0:01F6  8B4D04 
AX=0100  BX=0000 

DS=2E08  ES=2E08 

2CB0:01F9  8B5506 
AX=0100  BX=0000 

DS=2E08  ES=2E08 

2CB0:01FC  8B7508 
AX=0100  BX=0000 

DS=2E08  ES=2E08 

2CB0:01FF  8B7D0A 
AX=0100  BX=0000 

DS=2E08  ES=2E08 

2CB0:0202  55 
-T  5  <Enter> 


JMP  _int86+2C  (01E5) 

CX=0000  DX=0000  SP=0F66  BP=0F74  SI=0089  DI=1065 

SS=2E08  CS=2CB0  IP=01E5  NV  UP  El  PL  NZ  AC  PE  NC 

MOV  [BP-0C],SS  SS:0F68=0F74 


cx=oooo 

DX=0000 

SP=0F66 

SS=2E08 

CS=2CB0 

IP=01E8 

LEA  AX, 

[BP-OA] 

cx=oooo 

DX=0000 

SP=0F66 

SS=2E08 

CS=2CB0 

IP=01EB 

MOV  [BP-0E],AX 

cx=oooo 

DX=0000 

SP=0F66 

SS=2E08 

CS=2CB0 

IP=01EE 

MOV  DI, 

[BP+06] 

cx=oooo 

DX=0000 

SP=0F66 

SS=2E08 

CS=2CB0 

IP=01F1 

MOV  AX, 

[DI] 

cx=oooo 

DX=0000 

SP=0F66 

SS=2E08 

CS=2CB0 

IP=01F3 

MOV  BX, 

[DI+02] 

BP=0F74  SI=0089  DI=1065 

NV  UP  El  PL  NZ  AC  PE  NC 

SS:0F6A=60CD 

BP=0F74  SI=0089  DI=1065 

NV  UP  El  PL  NZ  AC  PE  NC 

SS:0F66=0060 

BP=0F74  SI=0089  DI=1065 

NV  UP  El  PL  NZ  AC  PE  NC 

SS:0F7A=0F82 

BP=0F74  SI=0089  DI=0F82 

NV  UP  El  PL  NZ  AC  PE  NC 

DS:0F82=01 00 

BP=0F74  SI=0089  DI=0F82 

NV  UP  El  PL  NZ  AC  PE  NC 

DS:0F84=0000 


CX=0000  DX=0000  SP=0F66 

SS=2E08  CS=2CB0  IP=01F6 
MOV  CX, [DI+04] 

CX=0000  DX=0000  SP=0F66 

SS=2E08  CS=2CB0  IP=01F9 
MOV  DX, [DI+06] 

CX=0000  DX=0000  SP=0F66 

SS=2E08  CS=2CB0  IP=01FC 
MOV  SI, [DI+08] 

CX=0000  DX=0000  SP=0F66 

SS=2E08  CS=2CB0  IP=01FF 
MOV  DI, [DI+OA] 

CX=0000  DX=0000  SP=0F66 

SS=2E08  CS=2CB0  IP=0202 
PUSH  BP 


BP=0F74  SI=0089  DI=0F82 

NV  UP  El  PL  NZ  AC  PE  NC 

DS:OF86=0000 

BP=0F74  SI=0089  DI=0F82 

NV  UP  El  PL  NZ  AC  PE  NC 

DS:0F88=0000 

BP=0F74  SI=0089  DI=0F82 

NV  UP  El  PL  NZ  AC  PE  NC 

DS:0F8A=0000 

BP=0F74  SI=0000  DI=0F82 

NV  UP  El  PL  NZ  AC  PE  NC 

DS;0F8C=0000 

BP=0F74  SI=0000  DI=0000 

NV  UP  El  PL  NZ  AC  PE  NC 


AX=0100 

DS=2E08 


AX=0100 

DS=2E08 


AX=0100 


AX=0100 


BX=0000 

cx=oooo 

DX=0000 

SP=0F64 

BP=0F74 

SI=0000 

DI=0000 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=0203 

NV  UP  El 

PL  NZ  AC 

PE  NC 

1  83ED0E 

SUB  BP, 

+0E 

BX=0000 

cx=oooo 

DX=0000 

SP=0F64 

BP=0F66 

SI=0000 

DI=0000 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=0206 

NV  UP  El 

PL  NZ  AC 

PE  NC 

i  FF5E00 

CALL  FAR  [BP+OO] 

S: 

BX=0000 

cx=oooo 

DX=0000 

SP=0F60 

BP=0F66 

SI=0000 

DI=0000 

ES=2E08 

SS=2E08 

CS=2E08 

IP=0F6A 

NV  UP  El 

PL  NZ  AC 

PE  NC 

O 

D 

o 

INT  60 

BX=0000 

cx=oooo 

DX=0000 

SP=0F5A 

BP=0F66 

SI=0000 

DI=0000 

ES=2E08 

SS=2E08 

CS=1313 

IP=0190 

NV  UP  DI 

PL  NZ  AC 

PE  NC 

1  80FC00 

CMP  AH, 

00 

BX=0000 

cx=oooo 

DX=0000 

SP=0F5A 

BP=0F66 

SI=0000 

DI=0000 

ES=2E08 

SS=2E08 

CS=1313 

IP=01 93 

NV  UP  DI 

PL  NZ  NA 

PO  NC 

1313:0193  7521 


JNZ 


01B6 
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When  the  Interrupt  60H  call  is  encountered  at  offset  0F6AH,  the  values  passed  to  it  can 
be  checked.  AH  contains  1  and  DX  contains  0 — the  correct  values  for  START  COMl. 

In  order  to  use  the  symbols  for  BADSCOP,  use  the  Open  Symbol  Map  command,  XO,  to 
switch  to  the  correct  symbol  map.  Then,  because  the  value  of  CSEG  is  not  defined  in  the 
map,  use  the  Set  Symbol  Value  command  to  set  CSEG  to  the  current  value  of  CS.  (CS  was 
changed  to  the  correct  value  for  BADSCOP  when  the  program  executed  the  INT  60H 
instruction.) 

-XO  BADSCOP !  <Enter> 

-Z  CSEG  CS  <Enter> 

-X?*  <Enter> 


CSEG:  (1313) 

0100  INITIALIZE  0103  OLD_COMM_INT  0107  COUNT  0109  STATUS 

01 OA  PORT  01  OB  BUFPNTR  01 OD  COMSCOPE  0190  CONTROL 

020A  VECTOR_INIT 

Because  the  BADSCOP  symbols  now  have  meaning,  a  great  deal  of  trouble  can  be  avoided 
by  setting  a  breakpoint  at  CONTROL^  the  entry  point  for  Interrupt  60H,  so  that  it  will  no 
longer  be  necessary  to  trace  the  ^int86  routine  to  find  the  INT  60H  command.  Execution 
will  automatically  stop  when  the  Interrupt  60H  handler  is  entered. 


-BP  CONTROL  <Enter> 


-BL  <Enter> 

0  e  2CB0:002E 

1  e  2CB0;0046 

2  e  2CB0:OO66 

3  e  2CB0:0086 

4  e  2CB0:008B 

5  e  2CB0:00AC 

6  e  2CB0:00C7 

7  e  2CB0:00F5 

8  e  1313:0190 


[ COMMSCMD  !  _TEXT :  _jnain+ 1 E 
[  COMMSCMD  !  -TEXT :  -jnain+3  6 
[COMMSCMD ! -TEXT: _main+5 6 
[  COMMSCMD  !  -TEXT :  _inain+7  6 
[COMMSCMD ! -TEXT :_main+7B 
[  COMMSCMD ! -TEXT : -main+ 9C 
[ COMMSCMD ! -TEXT : _main+B7 
[ COMMSCMD  !  -TEXT : _jnain+E5 
[CSEGS: CONTROL] 


(002E) ]  commscmd.C: 41 
(0046)1  commscmd.C: 42 
(0066)1  commscmd.C: 44 
(0086)1  commscmd.C: 46 
(008B) 1  commscmd.C : 49 
(OOAC) 1  commscmd.C: 53 
(00C7)1  commscmd.C: 58 
(00F5) 1  commscmd.C: 63 


With  the  housekeeping  tasks  done,  the  business  of  debugging  BADSCOP  can  begin.  The 
first  thing  CONTROL  does  is  check  for  a  stop  request.  If  no  stop  request  is  present,  the 
routine  jumps  to  the  check  for  a  start  request.  (The  first  test  and  jump  were  already  com¬ 
plete  when  the  trace  ended  above.)  The  test  for  a  start  request  is  passed.  CONTROL 
places  the  port  number  in  a  local  variable,  resets  the  buffer  pointer  and  the  buffer  count, 
and  turns  tracing  status  on.  With  all  this  complete,  CONTROL  returns. 


-T  5  <Enter> 
AX=01BB 
DS=2E08 
1313:01B 
AX=01BB 
DS=2E08 
1313:01B 
AX=01BB 
DS=2E08 


BX=E81E 

CX=3F48 

DX=0000 

SP=0F5A  ] 

ES=2E08 

SS=2E08 

CS=1313 

IP=01B6 

;  80FC01 

CMP  AH, 

01 

BX=E81E 

CX=3F48 

DX=0000 

SP=0F5A  1 

ES=2E08 

SS=2E08 

CS=1313 

IP=01B9 

»  751C 

JNZ  CONTROL+47  (( 

BX=E81E 

CX=3F48 

DX=0000 

SP=0F5A  ] 

ES=2E08 

SS=2E08 

CS=1313 

IP=01BB 

J  2E88160A01  1 

MOV  CS : 

:  [PORT] ,DL 

BP=0F66  SI=1CE7  DI=7400 
NV  UP  DI  PL  NZ  NA  PO  NC 

BP=0F66  SI=1CE7  DI=7400 
NV  UP  DI  PL  ZR  NA  PE  NC 
01D7) 

BP=0F66  SI=1CE7  DI=7400 
NV  UP  DI  PL  ZR  NA  PE  NC 

CS:010A=00 


(more) 
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AX=01BB  BX=E81E  CX=3F48  DX=0000  SP=0F5A 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01C0 

131 3: 01  CO  2EC7060B010202  MOV  Word  Ptr  CS 
AX=01BB  BX=E81E  CX=3F48  DX=0000  SP=0F5A 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01C7 

1313:01C7  2EC70607010000  MOV  Word  Ptr  CS 
-T  5  <Enter> 


AX=01BB 

BX=E81E 

CX=3F48 

DX=0000 

SP=0F5A 

DS=2E08 

ES=2E08 

SS=2E08 

CS=1313 

IP=01CE 

1313:01CE  2EC606090101  MOV  Byte  Ptr  C£ 

AX=01BB 

BX=E81E 

CX=3F48 

DX=0000 

SP=0F5A 

DS=2E08 

ES=2E08 

SS=2E08 

CS=1313 

IP=01D4 

1313:01D4 

1  EB2B 

JMP  CONTROL+71 

AX=01BB 

BX=E81E 

CX=3F48 

DX=0000 

SP=0F5A 

DS=2E08 

ES=2E08 

SS=2E08 

CS=1313 

IP=0201 

1313:0201 

CF 

I  RET 

AX=01BB 

BX=E81E 

CX=3F48 

DX=0000 

SP=0F60 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2E08 

IP=0F6C 

2E08:0F6C  CB 

RETF 

AX=01BB 

BX=E81E 

CX=3F48 

DX=0000 

SP=0F64 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=0209 

2CB0:0209  5D  POP  BP 


BP=0F66  SI=1CE7  DI=7400 
NV  UP  DI  PL  ZR  NA  PE  NC 
:  [BUFPNTR] ,VECTOR_INIT  (0209)  CS:010B=0202 

BP=0F66  SI=1CE7  DI=7400 
NV  UP  DI  PL  ZR  NA  PE  NC 
:  [COUNT] ,  0000  CS: 01 07=0002 

BP=0F66  SI=1CE7  DI=7400 
NV  UP  DI  PL  ZR  NA  PE  NC 
:  [STATUS], 01  CS: 01 09=01 

BP=0F66  SI=1CE7  DI=7400 
NV  UP  DI  PL  ZR  NA  PE  NC 
(0201  ) 

BP=0F66  SI=1CE7  DI=7400 
NV  UP  DI  PL  ZR  NA  PE  NC 

BP=0F66  SI=1CE7  DI=7400 
NV  UP  El  PL  NZ  AC  PE  NC 

BP=0F66  SI=1CE7  DI=7400 
NV  UP  El  PL  NZ  AC  PE  NC 


As  can  be  seen  from  the  trace,  CONTROL  performed  correctly,  so  execution  of  the  routine 
can  continue. 


-<G  <Enter> 

Communications  tracing  STARTED  for  port  COM1 : 

AX=002F  BX=0001  CX=0C13  DX=0000  SP=0FA6  BP=0000  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=00F5  NV  UP  El  PL  NZ  NA  PE  NC 

2CB0:00F5  C3  RET  ;BR7 

COMMSCMD  has  written  the  message  to  the  user  and  trapped  at  the  breakpoint  set  at  the 
end  o{_main.  The  Examine  Symbol  Map  command  now  shows  that  SYMDEB  has  auto¬ 
matically  switched  to  the  symbol  map  for  COMMSCMD. 

-X*  <Enter> 

[2CB0  COMMSCMD] 

[2CB0  -TEXT] 

2E08  DGROUP 
0000  BADSCOP 

1313  CSEG 

No  problems  have  been  encountered  with  the  START  command;  now  the  same  process  of 
checking  COMMSCMD  and  BADSCOP  must  be  repeated  for  the  STOP  command.  (Even  if 
problems  had  been  found  with  the  START  command,  it  would  be  imprudent  not  to  test  the 
other  commands — they  could  have  errors,  too.)  SYMDEB  could  be  exited  and  restarted 
with  new  commands,  but  this  would  mean  the  loss  of  the  painfully  created  set  of  break¬ 
points.  Instead,  a  new  copy  of  COMMSCMD  is  loaded  without  leaving  SYMDEB.  One 
problem  with  this,  however,  is  that  when  SYMDEB  loads  an  .EXE  file,  it  adds  the  value  of 
the  initial  CS  register  to  the  addresses  of  the  segments  in  the  symbol  map  whose  name 
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matches  the  .EXE  file.  This  is  fine  the  first  time  the  program  loads,  but  the  second  time,  all 
the  values  are  doubled  and  therefore  incorrect.  To  avoid  this  error,  the  addresses  must  be 
adjusted  before  the  load.  Use  the  Set  Symbol  Value  command  to  subtract  CS  from  each  seg¬ 
ment  name  in  COMMSCMD!.  The  Examine  Symbol  Map  command  shows  the  new  values. 

-Z  _TEXT  _TEXT-CS  <Enter> 

“Z  DGROUP  DGROUP-CS  <Enter> 

-X*  <Enter> 

[2CB0  COMMSCMD] 

[0000  -TEXT] 

0158  DGROUP 
0000  BADSCOP 

1313  CSEG 

The  Name  File  or  Command-Tail  Parameters  command,  N,  and  the  Load  File  or  Sectors 
command,  L,  can  now  be  used  to  load  a  new  copy  of  COMMSCMD.EXE. 

-N  COMMSCMD.EXE  <Enter> 

"*L  <Enter> 

-X*  <Enter> 

[2CB0  COMMSCMD] 

[2CB0  -TEXT] 

2E08  DGROUP 
0000  BADSCOP 

1313  CSEG 

Notice  that  the  segment  values  inside  COMMSCMD!  are  the  same  as  they  were  when  the 
program  was  first  loaded.  Use  the  Name  command  again,  this  time  to  set  the  command  tail 
to  contain  a  STOP  command  for  COMl.  The  breakpoint  table  from  the  first  execution  is 
still  set,  so  the  program  can  now  be  traced  in  the  same  way. 

“N  STOP  1  <Enter> 

“G  <Enter> 


AX=0022 

BX=0F84 

CX=001 9 

DX=0098 

SP=0F80 

BP=0FA6 

SI=0089 

DI=1 065 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=002E 

NV  UP  El 

PL  NZ 

NA  PO  NC 

41  : 

if  (0  ==  stricmp(argv[1],"STOP”) ) 

2CB0:002E  B83600 

MOV  AX, 

0036 

;BR0 

“G  <Enter> 

AX=0000 

BX=4 1 5A 

CX=0000 

DX=0098 

SP=0F80 

BP=0FA6 

SI=0089 

DI=1065 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=0046 

NV  UP  El 

PL  ZR 

NA  PE  NC 

42: 

cmd  = 

0; 

2CB0:0046  C746FC0000  MOV  Word  Ptr  [BP-04], 0000 

;BR1  SS:0FA2=0000 

“G  <Enter> 

AX=0000 

BX=415A 

cx=oooo 

DX=0098 

SP=0F80 

BP=0FA6 

SI=0089 

DI=1065 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=008B 

NV  UP  El 

PL  ZR 

NA  PE  NC 

49: 

if  (argc  ==  3) 

2CB0:008B  837E0403  CMP  Word  Ptr  [BP+04],+03 

;BR4  SS:0FAA=0003 

“G  <Enter> 

AX=0001 

BX=00D0 

cx=oooo 

DX=0000 

SP=0F80 

BP=0FA6 

SI=0089 

DI=1065 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=00AC 

NV  UP  El 

PL  NZ 

NA  PO  NC 

53: 

port  = 

port-1 ; 

(more) 
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2CB0:00AC  FF4EFA  DEC  Word  Ptr  [BP-06]  ;BR5  SS:OFAO=OO01 

-  G  <Enter> 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F7A  BP=0FA6  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=00C7  NV  UP  El  PL  ZR  NA  PE  NC 

2CB0:00C7  E8EF00  CALL  _int86  ;BR6 

COMMSCMD  detected  that  this  is  a  stop  request  for  COMl  and  set  the  arguments  for 
^int86  correctly.  Because  a  breakpoint  is  now  set  at  CONTROL,  tracing  until  the  Interrupt 
60H  call  is  found  is  not  necessary.  Simply  executing  the  program  will  cause  it  to  stop  at 
CONTROL 

-G  <Enter> 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F5C  BP=0F68  SI=7400  DI=E903 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=0190  NV  UP  DJ  PL  NZ  AC  PO  NC 

CSEG ; CONTROL : 

1313:0190  80FC00  CMP  AH, 00  ;BR8 

The  registers  are  set  correctly  for  a  stop  request  on  COMl  (AH  =  0,  DX  =  0).  The  routine 
can  now  be  traced  to  check  for  correct  operation.  First,  however,  a  quick  look  at  the  sym¬ 
bol  maps  shows  that  SYMDEB  has  automatically  switched  to  BADSCOP’s  symbols. 

-X*  <Enter> 

2CB0  COMMSCMD 

2CB0  -TEXT 
2E08  DGROUP 
[0000  BADSCOP] 

[1313  CSEG] 

- T  5  <Enter> 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F5C  BP=0F68  SI=7400  DI=E903 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=0193  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:0193  7521  JNZ  CONTROL+26  (01 B6) 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F5C  BP=0F68  SI=7400  DI=E903 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=0195  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:0195  IE  PUSH  DS 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F5A  BP=0F68  SI=7400  DI=E903 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=0196  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:0196  53  PUSH  BX 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F58  BP=0F68  SI=7400  DI=E903 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=0197  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:0197  OE  PUSH  CS 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F56  BP=0F68  SI=7400  DI=E903 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01 98  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:0198  IF  POP  DS 

- T  5  <Enter> 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F58  BP=0F68  SI=7400  DI=E903 

DS=1313  ES=2E08  SS=2E08  CS=1313  IP=0199  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:0199  C606090100  MOV  Byte  Ptr  [STATUS], 00  DS: 01 09=01 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F58  BP=0F68  SI=7400  DI=E903 

DS=1313  ES=2E08  SS=2E08  CS=1313  IP=019E  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:019E  8B1E0B01  MOV  BX, [BUFPNTR]  DS:010B=0202 

AX=001E  BX=0202  CX=0000  DX=0000  SP=0F58  BP=0F68  SI=7400  DI=E903 

DS=1313  ES=2E08  SS=2E08  CS=1313  IP=01A2  NV  UP  DI  PL  ZR  NA  PE  NC 

(more) 
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1313:01A2  C60780  MOV  Byte  Ptr  (BX] , 80  DS:0202=80 

AX=001E  BX=0202  CX=0000  DX=0000  SP=0F58  BP=0F68  SI=7400  DI=E903 

DS=1313  ES=2E08  SS=2E08  CS=1313  IP=01A5  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:01A5  C64701FF  MOV  Byte  Ptr  [BX+01],FF  DS:0203=FF 

AX=001E  BX=0202  CX=0000  DX=0000  SP=0F58  BP=0F68  SI=7400  DI=E903 

DS=1313  ES=2E08  SS=2E08  CS=1313  IP=01A9  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:01A9  FF060701  INC  Word  Ptr  [COUNT]  DS:0107=0000 

-T  5  <Enter> 

AX=001E  BX=0202  CX=0000  DX=0000  SP=0F58  BP=0F68  SI=7400  DI=E903 

DS=1313  ES=2E08  SS=2E08  CS=1313  TP=01AD  NV  UP  DI  PL  NZ  NA  PO  NC 

131 3: 01  AD  FF060701  INC  Word  Ptr  [COUNT]  DS: 01 07=0001 

AX=001E  BX=0202  CX=0000  DX=0000  SP=0F58  BP=0F68  SI=7400  DI=E903 

DS=1313  ES=2E08  SS=2E08  CS=1313  IP=01B1  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01B1  5B  POP  BX 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F5A  BP=0F68  SI=7400  DI=E903 

DS=1313  ES=2E08  SS=2E08  CS=1313  IP=01B2  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01B2  IF  POP  DS 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F5C  BP=0F68  SI=7400  DI=E903 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01B3  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01B3  EB4C  JMP  CONTROL+71  (0201) 

AX=001E  BX=3F48  CX=0000  DX=0000  SP=0F5C  BP=0F68  SI=7400  DI=E903 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=0201  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:0201  CF  IRET 

CONTROL  correctly  detected  that  this  was  a  stop  request.  It  then  saved  the  user’s  registers 
and  established  a  DS  equal  to  CS.  (Remember  that  BADSCOP  is  a  .COM  file  and  CS  =  DS  = 
SS.)  Having  done  this,  the  routine  moves  a  zero  to  STATUS,  which  turns  the  trace  off.  It 
then  moves  80H  FFH  to  the  buffer  to  indicate  the  end  of  a  trace  session,  increments 
COUNT  to  allow  for  the  new  entry,  and  restores  the  user’s  registers.  What  it  does  not  do 
is  increment  the  buffer  pointer  to  allow  for  the  stop  marker.  This  behavior  is  entirely  con¬ 
sistent  with  the  observed  phenomena:  When  a  trace  is  stopped  and  resumed,  the  stop 
marker  is  missing  and  the  count  is  one  too  high.  The  fix  is  to  add 


INC 

BX 

/INCREMENT  BUFFER  POINTER 

INC 

BX 

MOV 

BUFPNTR, BX 

to  the  CONTROL  procedure  before  the  registers  are  restored.  (Insert  these  lines  later  with 
your  favorite  editor.) 

Even  though  the  bug  has  been  found,  the  rest  of  the  routine  should  be  checked  for  other 
possible  bugs. 

-G  <Enter> 

Communications  tracing  STOPPED  for  port  COM1 : 

AX=002F  BX=0001  CX=0C13  DX=0000  SP=0FA8  BP=0000  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=00F5  NV  UP  El  PL  NZ  AC  PO  NC 

2CB0:00F5  C3  RET  ;BR7 

Loading  a  new  copy  of  COMMSCMD,  setting  the  command  tail  to  RESUME  1,  and  monitor¬ 
ing  program  execution  yields  the  following: 
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-N  COMMSCMD.EXE  <Enter> 

-Z  -TEXT  _TEXT-CS  <Enter> 

-Z  DGROUP  DGROUP-CS  <Enter> 

-X*  <Enter> 

[2CB0  COMMSCMD] 

[0000  -TEXT] 

0158  DGROUP 
0000  BADSCOP 

1313  CSEG 
-L  <Enter> 

-X*  <Enter> 

[2CB0  COMMSCMD] 

[2CB0  -TEXT] 

2E08  DGROUP 
0000  BADSCOP 

1313  CSEG 

-N  RESUME  1  <Enter> 

-G  <Enter> 

AX=0022  BX=0F82  CX=001 9  DX=0098  SP=0F7E  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=002E  NV  UP  El  PL  NZ  NA  PO  NC 

41:  if  (0  ==  stricmp (argv[1 ] , "STOP”) ) 

2CB0:002E  B83600  MOV  AX, 0036  ;BR0 

-G  <Enter> 

AX=0000  BX=415A  CX=0000  DX=0098  SP=0F7E  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=0086  NV  UP  El  PL  ZR  NA  PE  NC 

46:  cmd  =2; 

2CB0:0086  C746FC0200  MOV  Word  Ptr  [BP-04], 0002  /BR3  SS:0FA0=0000 

-G  <Enter> 

AX=0000  BX=415A  CX=0000  DX=0098  SP=0F7E  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=008B  NV  UP  El  PL  ZR  NA  PE  NC 

49:  if  (argc  ==  3) 

2CB0:008B  837E0403  CMP  Word  Ptr  [BP+04],+03  ;BR4  SS:0FA8=0003 

-G  <Enter> 

AX=0001  BX=00D0  CX=0000  DX=0000  SP=0F7E  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=00AC  NV  UP  El  PL  NZ  NA  PO  NC 

53:  port  =  port-1; 

2CB0:00AC  FF4EFA  DEC  Word  Ptr  [BP-06]  ;BR5  SS:0F9E=0001 

-G  <Enter> 

AX=0060  BX=00D0  CX=0000  DX=0000  SP=0F78  BP=0FA4  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=00C7  NV  UP  El  PL  ZR  NA  PE  NC 

2CB0:00C7  E8EF00  CALL  -int86  ;BR6 

-G  <Enter> 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=0190  NV  UP  DI  PL  NZ  AC  PE  NC 

CSEG : CONTROL : 

1313:0190  80FC00  CMP  AH, 00  ;BR8 

-T  5  <Enter> 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=0193  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:0193  7521  JNZ  CONTROL+26  (01 B6) 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01B6  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01B6  80FC01  CMP  AH, 01 

(more) 
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AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01B9  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01B9  751C  JNZ  CONTROL+47  (01D7) 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01D7  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01D7  80FC02  CMP  AH, 02 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01DA  NV  UP  DI  PL  ZR  NA  PE  NC 

131 3: 01  DA  7516  JNZ  CONTROL+62  (01 F2) 

-T  5  <Enter> 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01DC  NV  UP  DI  PL  ZR  NA  PE  NC 

1313:01DC  2E833E0B0100  CMP  . Word  Ptr  CS : [BUFPNTR] , +00  CS:010B=0202 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01E2  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01E2  741D  JZ  CONTROL+71  (0201) 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01E4  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01E4  2E88160A01  MOV  CS:[PORT],DL  CS:010A=00 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01E9  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01E9  2EC606090101  MOV  Byte  Ptr  CS ; [STATUS] , 01  CS: 01 09=00 

AX=0265  BX=001E  CX=3F48  DX=0000  SP=0F5A  BP=0F66  SI=0000  DI=7400 

DS=2E08  ES=2E08  SS=2E08  CS=1313  IP=01EF  NV  UP  DI  PL  NZ  NA  PO  NC 

1313:01EF  EB10  JMP  CONTROL+71  (0201) 


-T  5  <Enter> 


AX=0265 

BX=001E 

CX=3F48 

DX=0000 

SP=0F5A 

BP=0F66 

SI=0000 

DI=7400 

DS=2E08 

ES=2E08 

SS=2E08 

CS=1313 

IP=0201 

NV  UP 

DI 

PL  NZ 

NA  PO  NC 

1313:0201 

CF 

I  RET 

AX=0265 

BX=001E 

CX=3F48 

DX=0000 

SP=0F60 

BP=0F66 

SI=0000 

DI=7400 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2E08 

IP=0F6C 

NV  UP 

El 

PL  NZ 

AC  PE  NC 

2E08:0F6C  CB 

RETF 

AX=0265 

BX=001E 

CX=3F48 

DX=0000 

SP=0F64 

BP=0F66 

SI=0000 

DI=7400 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=0209 

NV  UP 

El 

PL  NZ 

AC  PE  NC 

2CB0:0209  5D 

POP  BP 

AX=0265 

BX=001E 

CX=3F48 

DX=0000 

SP=0F66 

BP=0F74 

SI=0000 

DI=7400 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=020A 

NV  UP 

El 

PL  NZ 

AC  PE  NC 

2CB0:020A  57 

PUSH  DI 

AX=0265 

BX=001E 

CX=3F48 

DX=0000 

SP=0F64 

BP=0F74 

SI=0000 

DI=7400 

DS=2E08 

ES=2E08 

SS=2E08 

CS=2CB0 

IP=020B 

NV  UP 

El 

PL  NZ 

AC  PE  NC 

2CB0:020B  8B7E08  MOV  DI, [BP+08]  SS:0F7C=0F90 

-G  <Enter> 

Communications  tracing  RESUMED  for  port  COM1 : 

AX=002F  BX=0001  CX=0C1 3  DX=0000  SP=0FA6  BP=0000  SI=0089  DI=1065 

DS=2E08  ES=2E08  SS=2E08  CS=2CB0  IP=00F5  NV  UP  El  PL  NZ  NA  PE  NC 

2CB0:00F5  C3  RET  ;BR7 

-Q  <Enter> 

The  processing  of  a  resume  request  is  correct.  Thus,  the  problem  with  stop  processing 
in  BADSCOP  was  the  only  problem.  The  corrected  BADSCOP,  which  is  actually 
COMMSCOP,  is  shown  in  Figure  18-4. 
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CodeView 

CodeView  is  the  most  sophisticated  debugging  monitor  produced  by  Microsoft.  It 
combines  the  philosophy  and  many  of  the  commands  of  its  predecessors,  DEBUG  and 
SYMDEB,  with  true  source-code  debugging.  The  availability  of  source  lines  and  symbols 
allows  CodeView  to  rival  the  convenience  of  program  development  and  debugging  pre¬ 
viously  available  only  in  interpreters  such  as  Microsoft  GW-BASIC.  However,  this  high  level 
of  interaction  with  the  source  program  is  also  the  root  of  its  problems  for  advanced 
debugging. 

In  order  to  provide  the  debugger  with  the  tools  to  debug  at  the  source-line  level  and  to 
interrogate  program  variables,  CodeView  is  required  to  have  a  detailed  knowledge  of  how 
high-order  languages  work  and  of  their  internal  conventions.  This  is  not  a  problem  for  lan¬ 
guages  like  C,  Pascal,  and  FORTRAN,  versions  of  which  are  produced  by  the  same  com¬ 
pany  that  created  CodeView.  The  object  code  generated  by  these  compilers  obeys  a 
stringent  set  of  rules  and  conventions.  Assembly-language  programs,  however,  tend  to  fol¬ 
low  their  own  rules  and  traditions,  making  them  quite  different  from  C  programs,  with 
their  own  separate  debugging  needs. 

C,  Pascal,  and  FORTRAN  programmers  will  find  CodeView  a  dream  to  use.  Assembly- 
language  programmers  using  versions  of  MASM  earlier  than  5.0  will  find  CodeView  cum¬ 
bersome  and  will  have  to  weigh  its  advantages  over  its  disadvantages.  All  users  will, 
however,  appreciate  the  good  design  and  programming  that  have  gone  into  CodeView.  It 
is  pleasing  to  know  that  someone  understands  the  programmer’s  debugging  needs  and  is 
trying  to  ease  the  burden. 

CodeView  has  added  several  welcome  functions  to  the  debugger’s  repertoire,  but  one 
of  these  new  features  towers  above  the  rest — watchpoints.  The  debugger  can  watch  the 
values  of  program  variables  or  expressions  and  set  breakpoints  on  them,  making  it  possi¬ 
ble  to  stop  execution  if  an  expression  evaluates  to  zero  or  if  a  location  changes.  Previous 
debugging  monitors  have  been  limited  to  tracing  and  breaking  on  instructions.  This  new 
facet  of  debugging  changes,  somewhat,  the  approach  to  resolving  a  bug. 

In  the  previous  discussion  of  debugging  techniques,  an  orderly  application  of  techniques 
from  inspection  and  observation  through  instrumentation  to  debugging  monitors  was 
recommended.  This  sequence  is  still  recommended  with  CodeView,  but  now  the  instru¬ 
mentation  features  have  been  integrated  into  the  debugging  monitor. 

A  simple  example 

The  following  example  shows  how  CodeView  uses  the  instrumentation  approach  to  isolate 
a  problem  and  then  uses  the  debugging  monitor  functions  to  solve  it.  The  example  is  also 
an  introduction  to  CodeView  commands  and  techniques.  The  commands  are,  for  the  most 
part,  similar  to  those  used  by  SYMDEB.  Those  commands  that  differ  greatly  are  indicated. 
This  example,  like  all  the  examples  and  demonstrations  in  this  article,  is  not  intended  to 
be  a  complete  tutorial — CodeView  commands  are  summarized  elsewhere  in  this  book 
and  explained  in  detail  in  the  manual  accompanying  the  product.  See  PROGRAMMING 
UTILITIES:  codeview.  The  example  simply  shows  some  of  the  more  common  CodeView 
commands  and  demonstrates  debugging  techniques  using  them. 
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UPPERCAS.C  (Figure  18-13)  is  a  simple  program  whose  sole  function  is  to  convert  a  canned 
string  to  uppercase.  When  executed,  the  program  prints  a  few  of  the  characters  from  the 
string  and  some  that  aren’t  in  the  string.  Inspecting  the  listing  doesn’t  reveal  the  cause  of 
the  problem.  (Some  readers  with  experience  writing  C  programs  will  see  the  cause  of  the 
problem,  because  it  is  quite  common;  pretend,  for  now,  that  the  listing  is  of  no  help  and 
enjoy  the  wonders  of  CodeView.) 

*  * 

♦  UPPERCAS . C  * 

♦  This  routine  converts  a  fixed  string  to  uppercase  and  prints  it.  * 

♦  * 

*dti4iiHiHiiiit:*;tiitiitiit:it:***********************************************************/ 


tinclude  <ctype.h> 

#include  <string.h> 

#include  <stdio.h> 

main (argc, argv) 

int  argc; 
char  *argv[]; 

{ 

char  *cp,c; 

cp  =  "a  stringXn”; 

/*  Convert  *cp  to  uppercase  and  write  to  standard  output  */ 

while  (*cp  !=  '\0') 

{ 

c  =  toupper (*cp++) ; 
put char (c) ; 

} 


Figure  18-13-  An  erroneous  C program  to  convert  a  string  to  uppercase. 

Like  SYMDEB,  CodeView  requires  some  special  preparation  to  produce  a  suitable  exe¬ 
cutable  file.  CodeView,  however,  makes  the  job  much  simpler.  Using  the  Microsoft  C  Com¬ 
piler,  compile  the  program  with 

OMSC  /Zi  UPPERCAS;  <Enter> 

(Remember  that  C  is  case  sensitive  when  interpreting  switches,  so  the  /Zi  switch  should 
be  entered  exactly  as  shown.)  The  /Zi  switch  instructs  the  compiler  to  generate  the  symbol 
tables  and  line-number  information  needed  by  CodeView.  Other  options  appropriate  to 
the  program  can  also  be  included,  but  /Zi  is  required. 

To  form  an  executable  file,  use  the  Microsoft  Object  Linker  (LINK)  as  follows: 

OLINK  /CO  UPPERCAS;  <Enter> 
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This  command  line  instructs  LINK  to  build  an  executable  file  with  the  information 
needed  for  CodeView.  Other  options  can  be  used  as  needed  or  desired.  The  output  of 
LINK,  UPPERCAS.EXE,  will  be  larger  than  a  .EXE  file  built  without  /CO  (about  2600  bytes 
larger  in  this  case),  but  the  program  will  run  correctly  when  executed  without  CodeView. 

Starting  CodeView  is  straightforward.  Simply  type 

OCV  UPPERCAS  <Enter> 

CodeView  loads  UPPERCAS.EXE.  It  locates  UPPERCAS.C,  the  source  file,  and  loads  that 
too.  It  then  presents  a  full-screen  display  similar  to  this: 


File  Uieu  Search  Run  Hatch  Options  Language  Calls  Help  |  F8=:Trace  F5=Go| 

I  uppercas.C  | 


i: 

2: 

3: 

4: 

S: 

S: 

7: 

3: 

9: 

10: 

11 : 

12: 

13: 

14: 

15: 

16: 

17: 

18: 


/mCKKKKimMMmimCKKIIKKMmmKKmCICICmilCICKXICKICKItMXICKKICKICKKICICICKXKKICKICKKKKKXKKXMl 

«  UPPERCAS.C 

*  This  routine  converts  a  fixed  string  to  uppercase  and  prints  it 


It  include  <ctype.h> 
Itinclude  <string.h> 
Itinclude  <stdio.h> 

nain(argcjargv) 

int  argc; 
char  «argv[]; 


licrosoft  (R)  CodeUieu  (R)  Mersion  2.0 

(C)  Copyright  Microsoft  Corp.  1986«  1987.  All  rights  reserved. 

> 


This  display  has  two  windows  open:  the  display  window,  which  shows  the  program  being 
debugged,  and  the  the  dialog  window,  which  currently  contains  only  the  copyright  notice 
and  a  prompt  (>)  for  input.  The  F6  function  key  moves  the  cursor  back  and  forth  between 
the  two  windows. 

CodeView  can  be  instructed  from  either  window  to  go  to  a  specific  line  (that  is,  to  execute 
until  a  specific  line  is  reached).  If  the  cursor  is  in  the  display  window,  use  the  arrow  keys 
to  select  a  line  and  press  the  F7  key.  Execution  will  proceed  until  the  selected  line  (or  the 
end  of  the  program)  is  reached.  To  start  execution  without  specifying  a  stop  line,  press  F5. 

The  same  functions  can  be  performed  from  the  dialog  window  using  typed  commands, 
which  may  seem  more  familiar.  Enter  the  Go  Execute  Program  command,  G,  optionally 
followed  by  an  address.  Execution  will  continue  until  the  specified  address  is  reached 
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or  until  stopped  by  something  else,  such  as  the  end  of  the  program.  In  this  sense,  the 
CodeView  Go  command  is  the  same  as  that  of  DEBUG  and  SYMDEB.  Unlike  those  rou¬ 
tines,  however,  CodeView’s  Go  command  does  not  allow  an  equals  operator  (=). 

The  address  for  the  Go  command  can  be  specified  in  several  ways.  Because  the  display 
window  is  currently  showing  only  source  lines,  it  is  appropriate  to  set  the  stop  location  in 
terms  of  line  numbers.  The  syntax  of  a  line-number  specification  is  the  same  as  in 
SYMDEB — simply  enter  the  line  number  preceded  by  a  period: 

>G  .27  <Enter> 

Note  that  the  line  number  is  specified  in  decimal.  This  seemingly  innocent  statement 
uncovers  one  of  the  problem  areas  in  CodeView,  especially  for  assembly-language  pro¬ 
grammers.  The  default  radix  for  CodeView  is  decimal.  This  convention  works  well  for 
things  associated  with  the  C  program,  such  as  line  numbers,  but  is  very  inconvenient  for 
addresses  and  other  similar  items,  which  are  usually  in  hexadecimal.  Hexadecimal  num¬ 
bers  must  be  specified  using  the  cumbersome  C  notation.  Thus,  the  number  FF3EH  would 
be  entered  as  0xff3e.  The  radix  can  be  changed  using  the  Change  Current  Radix  com¬ 
mand,  N  (different  from  the  DEBUG  and  SYMDEB  N  command).  (The  problems  associ¬ 
ated  with  hexadecimal  numbers  in  early  versions  of  CodeView  are  no  longer  present  in 
versions  2.0  and  later.) 

The  radix  problem  can  be  avoided,  for  the  moment,  by  using  labels.  Issue 

>G  _main  <Enter> 

to  cause  CodeView  to  execute  until  the  main  routine  is  reached.  CodeView  then  shows 


File 

Mieu  Search  Run  Hatch  Options  Language  Calls  Help  |  F8=Trace  F5=Go 

_ 1  _ _ _  r>  1  — - -  . 

9: 

10: 

11: 

12: 

13: 

14: 

It  include  <ctype.h> 

It  include  <string.h> 

It  include  <stdio.h> 

nain(argciargu) 

16: 

char  Kargull; 

17: 

18: 

19: 

char  «cp,c; 

20: 

21: 

cp  =  "a  stringSn”;  1 

22: 

§ 

23: 

Conuert  «cp  to  uppercase  and  urite  to  standard  output  1 

24: 

I 

25: 

uhile  («cp  != 

^S0')  1 

26: 

_  _  J 

Microsoft  (R)  CodeUieu  (R)  Uersion  2.0  U 

(C)  Copyright  Hicrosoft  Corp. 

1986,  1987.  All  rights  reserved.  J 

>g  nain 
> 

1 
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The  display  shows  line  15  in  reverse  video,  indicating  that  CodeView  has  stopped  there. 
This  is  the  first  line  of  the  mainO  module,  but  it  is  not  executable.  Press  the  FIO  key, 
which  has  the  same  effect  as  entering  the  Step  Through  Program  command,  P,  in  the  dia¬ 
log  window,  to  cause  line  19  to  be  executed.  The  reverse  video  line  is  then  21,  which  is  the 
next  line  to  be  executed. 

To  see  the  changes  to  cp,  *cp,  and  c,  establish  a  watch  on  these  three  variables.  To  use  the 
Watch  Word  command,  WW,  for  the  word  cp,  type 

>WW  cp  <Enter> 

When  entered  from  the  dialog  window,  this  command  opens  the  watch  window  at  the  top 
of  the  screen  and  displays  the  current  value  of  cp.  To  display  the  expression  at  *cp,  use  the 
Watch  Expression  command,  W?,  as  follows: 

>W?  cp, s  <Enter> 

This  expression  will  display  the  null-delimited  string  at  *cp.  Finally,  to  see  the  ASCII  char¬ 
acter  value  of  c,  use  the  Watch  ASCII  command,  WA: 

>WA  c  <Enter> 

The  results  of  these  watch  commands  are  shown  in  the  following  screen: 


File  Mieu  Search  Sun  Watch  i^tions  Language  Calls  Help  |  F8=Trace  F5=Go 
- |  UpperCaS.C  | . .  .  '  . . - .  \ 


0)  cp 

:  55C4:0FF0  5527 

P  cp.s  :  "" 

Z)  c 

:  55C4:eFF2  . 

9: 

ft include  <ctype.h> 

10 : 

tl include  <string.h> 

I 

11 : 

ttinclude  <stdio.h> 

1 

12: 

1 

13: 

nain(argc«argv) 

14: 

1 

15: 

ini  argc; 

16: 

char  «argu[]; 

17: 

18: 

19: 

char  «cp,c; 

ZO: 

21: 

cp  =  "'a  stringSn''; 

B 

S 

i 

I 

The  values  displayed  in  the  watch  window  are  not  yet  defined  because  line  21,  which 
initialized  cp,  has  not  been  executed.  Press  F8  to  rectify  this.  Press  it  again  to  bring  the  ex¬ 
ecution  of  the  program  into  the  main  loop. 
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File  Uieu  Search  Run  Hatch  Options  Language  Calls  Help  |  F8=Trace  F5=Go| 

^  uppercas.C  | - - - - ..  . = 


9)  cp  :  55C4:0FF0  0036 

1)  cpjS  :  *'a  string 

2)  c  :  5SC4:0FF2  . 


18: 

19: 

20: 

21: 

22: 

23: 

24: 

25: 

26: 

ir 

28: 

29: 

30: 

31: 


char  «cpic; 

cp  =  ”a  stringSn”; 

Convert  «cp  to  uppercase  and  write  to  standard  output 

while  («cp  !=  'S0M 
{ 


c  =  toiipper(«cp++) ; 


putchar(c); 

> 


>ww 

>w? 

>wa 

> 


cp 

cp,s 

c 


The  pointer  cp  now  contains  the  correct  address.  The  Display  Memory  command,  D, 
could  be  used  to  display  the  contents  of  DS:0036H,  just  as  in  DEBUG  and  SYMDEB.  (This 
step  is  not  necessary,  however,  because  there  is  a  formatted  display  of  memory  in  the 
watch  window  at  1).  The  variable  c  has  not  yet  been  initialized. 
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Press  the  F8  key  to  execute  line  27.  A  curious  and  unexpected  thing  happens,  as  shown  in 
the  next  screen: 


File  Vieu 

Search  Run  Hatch  Options  Language  Calls  Help  I  F8=Trace  F5=Go 
_ 1  _ _ /%  1 _ _ 

- - ^  1 - 

El)  cp  :  55C4:0FF0  0038 

1)  cp,s  :  "string 

2)  c  :  5BC4:0FF2 

18:  { 

19:  char 

20: 

21: 

22: 

23: 

24: 

25: 

26: 

27: 

^Pjc:  1 

cp  =  "a  stringSn";  i 

/*  Convert  «cp  to  uppercase  and  urite  to  standard  output  1 

uhile  («cp  ?=  '\0M  1 

c  =  toupper(«cp+*);  | 

28: 

putchar(c);  | 

’  I 

>UU  cp 

>U?  CpjS 

>ua  c 
> 

1 

Notice  that  the  value  of  cp  has  changed  from  0036H  to  0038H.  The  line  of  code,  however, 
indicates  that  the  pointer  should  have  been  incremented  by  only  one  (^0!?++).  The  second 
character  of  the  string,  a  blank,  has  been  loaded  into  c.  This  could  explain  the  apparent 
random  selection  of  characters  being  displayed  (actually  every  other  character)  and  the 
garbage  characters  displayed  (the  zero  at  the  end  of  the  string  might  be  skipped,  causing 
the  routine  to  continue  converting  until  a  zero  is  encountered  somewhere  in  memory). 

Source-line  debugging  does  not  reveal  enough  about  what  is  happening  in  this  case.  To 
look  more  closely  at  the  mechanism  of  the  program,  the  program  must  be  restarted. 
Before  doing  this,  set  a  breakpoint  at  line  27: 

>BP  .27  <Enter> 
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Then  restart  (actually,  reload)  the  program  with  the  Reload  Program  command,  L.  Note 
that  watch  commands  and  breakpoints  are  preserved  when  a  program  is  restarted. 
Executing  the  restarted  program  with  G  yields 


File  Uieu  Search  Run  Hatch  options  Language  Calls  Help  |  F8=Trace  F5=Go| 

uppercas.C  |  :  ■  t:- 


9)  cp  :  55C4:0FF0  0036 

1)  cpiS  :  *'a  string 

2)  c  :  S5C4:0FF2  . 


18: 
19: 
20: 
21 : 
22: 
23: 
24: 
25: 
26: 


char  «cpic; 

cp  =  "a  stringSn”; 

/»  Convert  «cp  to  uppercase  and  urite  to  standard  output 
uhile  (^p  ?=  'S0M 


28: 

29: 

30: 

3i:  } 

putchar(c); 

> 

>bp  .27 
>1 

>g 

> 

_ 

The  display  shows  line  27  in  reverse  video,  indicating  that  it  is  the  next  line  to  be  executed. 
The  pointer  cp  has  the  correct  value,  as  shown  in  the  watch  window.  Now  Press  the  F2  key 
to  turn  on  the  register  display  and  press  F3  to  show  the  assembly  code. 
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File  Vieu  Search  Run 


9) 

1) 

2) 


cp  :  55C4:0FF0  0036 
cpiS  :  "a  string 
c  :  5SC4:0FF2  . 


Hatch  (^tions  Language 
^  uppercas.C  | 


Calls  Help  |  F8=Trace  F5=Go| 


>bp  .27 
>1 
\>9 


27: 

c  =  toupperC^^*): 

15^527:0026  FF16FC 

INC 

UorH  Ptr  [cpl 

;BRfi  f 

5527:0029  8A07 

NOM 

ALiB(^te  Ptr  [BX] 

1 

5527:002B  98 

CBU 

1 

5527:002C  8BD8 

HOU 

BX.AX 

1 

5527:802E  F687B30102 

TEST 

Bi^te  Ptr  [BX^01B3]|02 

1 

5527:0033  740C 

JZ 

_nain«31  (8841) 

S527:ee35  8B5EFC 

MOU 

BXfUopd  Ftp  [cp] 

S527:ee38  FF46FC 

INC 

Word  Ptr  [cp] 

5527:003B  eA07 

HOU 

ALiByte  Ptr  [BX] 

5527:003D  2C20 

SUB 

ALi20 

5527:003F  EB08 

JMP 

j>iain+39  (0049) 

5527:0041  8B5EFC 

HOU 

BXiUord  Ptr  [cp] 

5527:0044  FF46FC 

INC 

Uord  Ptr  [cp] 

,= 

AX  =  0004 
BX  =  0036 
CX  =  0019 
DX  =  00B8 
SP  =  0FF0 
BP  =  0FF4 
SI  =  00A9 
DI  s  10DS 
DS  =  SSC4 
ES  =  55C4 
SS  55C4 
CS  s  5S27 
IP  =  0026 

NU  UP 
El  PL 
NZ  NA 
PO  NC 

SS:0FF0 

0036 


The  display  highlights  line  27,  indicating  that  a  breakpoint  exists  at  this  line.  The  line  of 
code  at  CS:0026H  is  in  reverse  video,  indicating  that  it  is  the  next  line  to  be  executed. 

The  previous  instruction  has  loaded  BX  with  [cp].  The  first  thing  the  code  for  line  27 
does  is  increment  the  word  at  memory  location  [cp]  The  initial  value  of  cp  is  in  BX,  so  the 
♦cp++  request  can  now  be  executed.  Use  the  F8  key  to  single-step  through  the  lines  of 
code.  Notice  that  when  only  source  lines  are  on  the  screen,  F8  steps  one  source  line  at  a 
time,  but  when  assembly  code  is  shown,  F8  steps  one  assembly  line  at  a  time.  Single¬ 
stepping  through  the  code,  note  how  the  registers  and  watch  window  change.  Everything 
appears  normal  until  CS:0038H  is  executed. 
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Fi le  Uieu  Search 

Run  Hatch  Options  Language  Calls  Help  |  F8=Trace  F5=Go 

9)  cp  :  55C4:eFF0 

0038 

AX  =  0061 

1)  cpiS  *'striiiig 

BX  =  0037 

2)  c  :  55C4:eFF2 

• 

OX  =  0019 

nV  -  RADQ 

J/A  *-  OuoO 

27: 

c  =  tauFperC«cp«'-i‘);  E 

SP  =  0FF0 

5527:0826  FF46FC 

INC 

iiiira  Ptr  [cp]  :m« 

BP  =  0FF4 

5527:0029  8A07 

MOM 

AL^Byte  Ptr  CBXl 

SI  =  00A9 

5527:002B  98 

OBU 

DI  =  10D5 

5527:0020  8BD8 

MOM 

BX^AX 

BS  =  5504 

5527:002E  F687B30102 

TEST 

Byte  Ptr  [BX+01B3],02 

ES  =  5504 

5527:0033  7400 

JZ 

nain+31  (0041) 

SS  =  5504 

5527:0035  8B5EF0 

MOM 

BXiUord  Ptr  [cp] 

OS  =  5527 

5^7:  0038  FF46F0 

INC 

Uord  Ptr  Ecp] 

IP  =  003B 

5527:003D  2020 

SUB 

ALi20 

MM  UP 

5527:003F  EB08 

JMP 

_nain+39  (0049) 

El  PL 

5527:0041  8B5EF0 

MOM 

BXfUord  Ptr  [cp] 

NZ  NA 

5527:0044  FF46F0 

INC 

Uord  Ptr  [cp] 

t 

PO  NO 

>bp  .27 

]  DS:0037 

>1 

1  20 

>g 

> 

_ 

Notice  that  the  value  of  cp  in  the  watch  window  has  incremented  again.  The  line  of  C 
code  has  two  increments  hidden  in  it,  not  the  expected  single  increment.  Why  is  this? 

To  find  the  answer,  examine  the  toupperQ  macro.  The  following  definition,  extracted 
from  CTYPE.H,  explains  what  is  happening: 


#define  -UPPER 
#define  -LOWER 
#define  isupper(c) 
#define  islower(c) 


0x1  /*  uppercase  letter  */ 

0x2  /*  lowercase  letter  */ 

(  (-Ctype+1 )  [c]  &  -UPPER  ) 

(  {-ctype+1 ) [c]  &  -LOWER  ) 


#define  — tolower(c)  (  (c)-*A'+*a'  ) 

#define  — toupper(c)  (  (c)-'a'+'A'  ) 


#define  toupper(c)  (  (islower(c))  ?  — toupper(c)  :  (c)  ) 

#define  tolower(c)  (  (isupper(c))  ?  — tolower(c)  :  (c)  ) 

The  argument  to  toupperQ,  c,  is  used  twice,  once  in  the  macro  that  checks  for  lowercase, 
islowerQ,  and  once  in  ..toupperQ,  The  argument  is  replaced  in  this  case  with  *cp++, 
which  has  the  famous  C  unexpected  side  effects.  Because  the  unary  post-increment  is  the 
handiest  way  to  perform  the  function  desired  in  the  program,  fixing  the  problem  by 
changing  the  code  in  the  main  loop  is  undesirable.  Another  solution  to  the  problem  is  to 
use  the  function  version  of  toupperQ.  Because  toupperQ  is  defined  as  a  function  in 
STDIO.H,  simply  deleting  Mnclude  <ctype.h>  would  solve  the  problem.  Unfortunately, 
this  would  also  deprive  the  program  of  the  other  useful  definitions  in  CTYPE.H.  (Admit¬ 
tedly,  the  features  are  not  currently  used  by  the  program,  but  little  programs  sometimes 
grow  into  mighty  systems.)  So  to  keep  CTYPE.H  but  still  remove  the  macro  definition  of 
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toupperCX  use  the  #undef  command.  (Because  tolowerQ  has  the  same  problem,  it  should 
also  be  undefined.)  The  corrected  listing  is  shown  in  Figure  18-14. 


*  * 

*  UPPERCAS . C  * 

*  This  routine  converts  a  fixed  string  to  uppercase  and  prints  it.  * 

*  * 


#include  <ctype.h> 

#undef  toupper 
#undef  tolower 
#include  <string.h> 

#include  <stdio.h> 

main (argc, argv) 

int  argc; 
char  *argv[]; 

{ 

char  *cp,c; 

cp  =  "a  stringXn”; 

/*  Convert  *cp  to  uppercase  and  write  to  standard  output  */ 

while  (*cp  !=  ’\0') 

{ 

c  =  toupper (*cp++) ; 
put char  (c) ; 

} 


Figure  18-14.  The  corrected  version  of  UPPERCAS.  C. 

An  example  using  screen  output 

A  problem  with  DEBUG  is  that  it  writes  to  the  same  screen  as  the  program  does.  Both 
SYMDEB  and  CodeView,  however,  allow  the  debugger  to  switch  back  and  forth  between 
the  screen  containing  the  program’s  output  and  the  screen  containing  the  debugger’s  out¬ 
put.  This  feature  is  a  special  option  with  SYMDEB  and  is  sometimes  clumsy  to  use,  but 
with  CodeView,  keeping  a  separate  program  output  screen  is  automatic  and  switching 
back  and  forth  involves  simply  pressing  a  function  key  (F4). 

The  following  example  program  is  intended  to  display  an  ASCII  lookup  table  with  all  the 
displayable  characters  available  on  an  IBM  PC.  The  expected  output  is  shown  in  Figure 
18-15. 
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Oasctbl 

ASCII  LOOKUP  TABLE 

0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

9 

B 

f 

♦ 

♦ 

n 

* 

1 

y 

◄ 

X 

1! 

§ 

1 

t 

i 

Z 

! 

II 

tt 

$ 

X 

& 

J 

( 

) 

- 

, 

/ 

3 

0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

9 

< 
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> 

7 

4 

0 

a 

B 

C 

D 

E 

F 

G 

H 

I 

J 

K 

L 

n 

N 

6 

5 

p 

Q 

R 

S 

T 

U 

U 

U 

X 

y 

Z 

E 

S 
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& 

a 

b 

c 

d 

e 

f 

9 

h 

i 

J 

k 

1 

n 

n 

0 

7 

p 

q 

r 

s 

t 

u 

V 

u 

X 

9 

z 

1 

1 

} 

B 

Q 

u 

e 

a 

a 

a 

» 

a 

S 

A 

e 

e 

\ 

e 

1 

A 

1 

\ 

1 

K 

« 

A 

9 

E 

» 

a 

6 

0 

0 

a 

u 

y 
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U 

0 

£ 

¥ 

R 

f 

a 

1 

0 

u 

fi 

fi 

a 

s 

1 

I- 

“1 

« 

B 

C 

ji:) 

f 

! 

1 

y 

1 

1 

1 

f 

1 

1 

ff 

1 

R 

If 

11 

1} 

■ 

Jl 

J 

Jl 

1 

D 

Jl 

T 

IT 

k 

f 

IT 

1 

+ 

Jf 

r 

1 

r 

1 

■ 

E 

oc 

P 

r 

n 

<r 

P 

T 

s 
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0 

5 

ID 

0 

C 

n 

F 

= 

♦ 

> 

< 

r 

J 

f 

0 

• 

n 

2 

■ 

Figure  18-15.  The  output  expected  from  ASCTBL C. 

The  program  that  should  produce  this  display,  ASCTBL.C,  is  shown  in  Figure  18-16. 


*  * 

*  ASCTBL.C  * 

*  This  program  generates  an  ASCII  lookup  table  for  all  displayable  * 

*  ASCII  and  extended  IBM  PC  codes,  leaving  blanks  for  nondisplayable  * 

*  codes.  * 

*  * 


#include  <ctype.h> 
#include  <stdio.h> 


main  ( ) 

{ 

int  i,  j,  k; 

/*  Print  table  title.  */ 

printf (”\n\n\n  ASCII  LOOKUP  TABLE\n\n"); 

/*  Print  column  headers.  */ 

printf (”  "); 

for  (i  =  0;  i  <  16;  i++) 

printf ("%X  ”,  i); 

fputchar  (”\n") ; 

Figure  18-16.  An  erroneous  program  to  display  ASCII  characters. 


(more) 
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Something  is  clearly  wrong.  The  output  is  jumbled  and  no  pattern  is  immediately  obvious. 
To  locate  the  problem,  first  prepare  a  .EXE  file  and  start  CodeView  as  follows: 

C>MSC  /Zi  ASCTBL;  <Enter> 

OLINK  /CO  ASCTBL;  <Enter> 

OCV  ASCTBL  <Enter> 

CodeView  starts  and  displays  the  following  screen: 


File  Uieu  Search  Rum  Hatch  Language  Calls  Help  |  F8=Trace  F5=Go| 

'  . . '"I  asctbl.C  I  ■■  ■ 


i: 

2: 

3: 

4: 

5: 

7: 

b: 

9: 

10: 

11: 

12: 

13: 

14: 

15: 

16: 

17: 

18: 


/MICKICKICmCIIKICXKKKKICICmilCMICMKICXMlHmKKMMKMKMMKKICKKICKKXKMKKICMMKXKICXKICKKKKXKlcjj 


«  ASCTBL.C 

M  This  progran  generates  an  ASCII  lookup  table  for  all  displayable 
»  ASCII  and  extended  IBNPC  codes 1  leaving  blanks  for  nondi splay able 
*  codes . 


ft include  <ctype.h> 
ft include  <stdio.h> 

nainO 

int  ij  j«  k; 

Print  table  title. 
prlntf("\nSnSn 


<1/ 


ASCII  LOOKUP  TABLESnSn"): 


Hicrosoft  (B)  CodeUieu  (R)  Uersion  2.0 
(C)  Copyright  Microsoft  Corp.  1986 j  1987. 


All  rights  reserved. 


The  start  of  the  source  program  is  shown  in  the  display  window  and  the  dialog  window 
contains  an  input  prompt.  Press  the  FlO  key  three  times  to  bring  execution  to  line  21. 
(Remember  that  the  line  indicated  in  reverse  video  has  not  yet  been  executed.) 
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ascthl.C  I —  li  .TT...  -■  [ 


ftinclude  <ctype.h> 

^include  <stdio.h> 

nainO 

i 

int  ii  jf  k; 

Print  table  title. 
printf("SnSn\n 

Print  column  headers. 


printf (” 


ASCII  LOOKUP  TABLESnSn’’); 


for  (i  =  0;  i  <  16;  i++) 
printf(‘V.X  ”,  i); 
fputchar(”Sn”); 

Print  each  line  of  the  table. 


iicrosoft  (K)  CodeUieu  (R)  Uersion  2.0 

(C)  Copyright  llicrosoft  Corp.  1986,  1987.  All  rights  reserved. 


The  display  heading  has  been  printed  at  line  18.  Press  the  F4  key  to  display  what  the  pro¬ 
gram  has  written  on  the  screen. 


>cu  asctbl 


ASCII  LOOKUP  TABLE 
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Note:  Any  information  on  the  screen  when  you  started  CodeView  will  remain  on  the  vir¬ 
tual  output  screen  until  program  execution  clears  it  or  forces  it  to  scroll  off. 

The  table  heading  has  been  properly  written  to  the  screen.  Press  the  F4  key  again  to  return 
to  the  CodeView  display.  Continue  executing  the  program  with  the  FIO  key  to  bring  the 
program  to  line  24. 


File  Mieu  Search  Rum  Hatch  0]ptions  Language  Calls  Help  |  F8=Trace  F5=Go| 

— I  asctbl.C  |- .  ■■■  - 


ASCII  LOOKUP  TABLESnSn*’); 


10 : 
11 : 
12: 
13: 
14: 
15: 
16: 
17: 
18: 
19: 
20: 
21 : 
22: 
23: 

ar 

25: 

26: 


Microsoft  (R)  CodeUieu  (R)  Uersion  2.0 

(C)  Copyright  Microsoft  Corp.  1986«  1987.  All  rights  reserved. 


ft include  <ctype.h> 
ft include  <stdio.h> 

nainO 

i 

int  ij  ji  k; 

Print  table  title. 
printf ("SnSnSn 

Print  column  headers. 
printfC”  "); 
for  (i  =  0;  i  <  16; 

printf(”xX  ”,  i); 


fputcliar(  Sn  ) 


Print  each  line  of  the  table. 


At  this  point  in  program  execution,  the  column  headings  have  been  written  on  the  screen. 
Press  the  F4  key  again  to  see  the  results. 


634  The  MS-DOS  Encyclopedia 


Article  18:  Debugging  in  the  MS-DOS  Environment 


>cu  asctbl 


ASCII  LOOKUP  TABLE 

123456789ABCDEF 


The  output  of  the  program  is  still  correct,  so  allow  execution  to  continue  by  pressing  F4  to 
return  to  the  CodeView  screen  and  then  pressing  the  FIO  key.  This  will  execute  the  call  to 
the  fputcharO  function  to  write  a  newline  character. 

File  Uieu  Search  Sim  Hatch  Options  Language  Calls  Help  |  F8=Trace  F5=Go| 

21 :  printfC"  ");  D 

22:  for  (i  =  0;  i  <  16;  i*+)  I 

23:  printfC’xX  ”,  i);  I 

24:  fputchar("Sn");  I 

25:  I 

26:  Print  each  line  of  the  table.  § 


Print  first  hex  digit  of  symbols  on  this  line. 
printf(”xX  ”,  i); 

Print  each  of  the  16  symbols  for  this  line. 
for  (J  =  0;  J  <  16;  J*+) 

Filter  non-pr intable  characters. 
if  ((h  >=  7  aa  k  <::  13)  II  (k  >=  28  aa  k  <=  31) 
printft”  ”); 

else 

printf(”xc  ”,  k); 
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Examination  of  the  output  screen  shows  that  the  display  is  now  incorrect. 


Ocu  asctbl 

ASCII  LOOKUP  TABLE 

012345A789ABCDEFh 


A  lowercase  h  has  been  written  to  the  screen  instead  of  a  newline  character.  Further  ex¬ 
ecution  demonstrates  that  newline  characters  written  with  fputcharQ  are  not  working.  A 
closer  inspection  of  the  fputcharQ  function  is  needed. 

To  see  what  is  happening,  use  the  Reload  Program  command  to  restart  execution  at 
the  top  of  the  program.  Change  the  cursor  window  with  the  F6  key,  use  the  arrow  keys 
to  place  the  cursor  on  line  24,  and  press  F7.  This  brings  execution  back  to  line  24,  where 
fputcharQ  is  called.  Press  the  F3  key  to  place  the  display  in  assembly  mode  and  the  F2 
key  to  show  the  CPU  registers  and  flags.  The  first  assembly  instruction  of  the  fputcharQ 
function  call  is  about  to  be  executed. 
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File  Uieu  Search  Run  Hatch  lotions  Language  Calls  Help  |  F8=Trace  F5=Go 

asctbl.C  I  ••  I 

:  _ fputchar(”Sn”); _  QA 

BX  =  0001 
C 


DX  =  03Ce 


►527:004E  B86800 

MOU 

AX, 0068  i 

;527:0051  50 

PUSH 

AX 

1527:0052  E83F01 

CALL 

.fputchar  (0194) 

;527:0055  83C402 

ADD 

SP,*02 

17:  for  ( 

i  =  01  k  =  0; 

:  i  <  16;  !♦♦) 

1527:0058  C746FE0000 

MOU 

Uord  Ptr  [i] 10000 

;527:005D  C746FA0000 

MOU 

Uord  Ptr  [kl 10000 

1527:0062  837EFE10 

CMP 

Uord  Ptr  [i]j+10 

1527:0066  7D68 

JGE 

nain-^cO  (00D0) 

;527:0068  EB05 

JMP 

_nain*5f  (006F) 

;527:006A  FF46FE 

IMC 

Uord  Ptr  [i] 

;527:006D  EBF3 

JMP 

jiiain‘1‘52  (0062) 

10: 

printf("xX 

",  i); 

;527:006F  FF76FE 

PUSH 

Uord  Ptr  [il 

^527:0072  B86A00 

MOU 

AX,006A 

;527:0075  50 

PUSH 

AX 

;527:0076  E84801 

CALL 

.printf  (01C1) 

Nicposoft  (B)  CodeUieu  (B)  Uersion  2.0 
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Notice  that  the  parameter  being  passed  to  the  function  by  means  of  the  stack  is  0068H.  Use 
the  Display  Memory  command  to  display  DS:0068H.  (Note  the  hexadecimal  notation.) 


Uieu  Search  Run  Hatch 


MBMi] 

:0051  50 
:0052  E83F01 
:0055  83C402 


fputchar(”Nn**); 

PUSH 

1  CALL 

2  ADD 
for  (  i  =  01  k 


Options  Language  Calls  Help 
asctbl.C  I"  ^  • 

AX 

Jputchar  (0194) 

SP,*02 

=  0;  1  <  16;  1++) 


5527:0058  C746FE0000 

MOU 

Uord  Ptr  [i],0000 

5527:005D  C746FA0000 

MOU 

Uord  Ptr  [k]|OO00 

5527:0062  837EFE10 

CMP 

Uord  Ptr  [i],+10 

5527:0066  7D68 

JGE 

jqain'i'C0  (00D0) 

5527:0060  ED05 

JMP 

nain+Sf  (O06F) 

5527: 006A  FF46FE 

INC 

Uord  Ptr  [il 

5527:006D  EBF3 

JMP 

nain+52  (0062) 

30: 

printfCxX 

",  i); 

5527:006F  FF76FE 

PUSH 

Uord  Ptr  [i] 

5527:0072  B86A00 

MOU 

AX,006A 

5527:0075  50 

PUSH 

AX 

5527:0076  E84801 

CALL 

j»rintf  (01C1) 

>1 

>d  0x68  L8 

566D:0060 

> 

-0A  00  25  58  20  20 

F8=Trace  F5=6o 

1AX  =  0003 
BX  =  0001 
CX  =  0001 
DX  =  03C0 
SP  =  0F90 
BP  =  0F96 
SI  =  00A9 
DI  =  1075 
DS  =  566D 
ES  =  566D 
SS  =  566D 
CS  =  5527 
IP  =  004E 
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The  contents  of  memory  at  this  address  consist  of  a  null-delimited  string  containing  a 
newline  character.  The  representation  of  \n  is  correct.  To  see  how  the  string  is  handled, 
use  the  trace  key,  F8,  to  single-step  through  fputcharO  and  subordinate  functions.  These 
functions  are  complicated;  nearly  100  steps  are  required  to  reach  the  MS-DOS  Interrupt 
21H  call  that  actually  writes  the  screen. 


Fi  le  Uieu  Search 

Run  Watch 

Cations  Language  Calls  Help  I  F8=Trace  F5=Go| 

j 

L.  1  ... 

1 

dsdbi  i>--  >< 

j 

5527:10E9  51 

PUSH 

CX 

E 

8X  =  4008 

5527:10EA  8BCF 

HOM 

CX^DI 

BX  =  0001 

5527:10EC  2BC8 

SUB 

CX^DX 

I 

CX  =  0001 

DX  =  0F84 

5527:10F0  9C 

PUSHF 

SP  =  0F68 

5527:10F1  03F0 

8DD 

ShOX 

BP  =  0F6E 

5527:10F3  9D 

POPF 

SI  =  0000 

5527:10F4  7304 

JNB 

urite^82  (10F8) 

DI  =  0F85 

5527:10F6  B409 

NOU 

6H^09 

DS  =  566D 

5;527:10F8  EBIA 

JMP 

write+9c  (1114) 

ES  =  566D 

S527:10F8  0BC0 

OR 

OX^OX 

SS  =  566D 

B527:10FC  7516 

JNZ 

upite*9c  (1114) 

CS  =  5527 

B527:i0FE  F637120240 

TEST 

Byte  Ptr  IBX+_osf ile],40 

IP  =  10EE 

B527:1103  740B 

JZ 

upite+98  (1110) 

B527:ll05  8B5E06 

HOU 

BX^Uord  Ptr  [BP^06] 

NU  UP 

B527:ll08  803F18 

CMP 

Byte  Ptr  [BX],16 

El  PL 

B527:110B  7503 

JNZ 

_write*98  (1110) 

NZ  N8 

B527:110D  F8 

CLC 

t 

PO  NC 

B66D:0060 

-08  00  25  58  20  20  20  00 

. 

>d  0xf84  L8 

B66D:0F80 

> 

68  00  DC  00-A9  00  96  0F 

H 

The  AH  register’s  contents,  40H,  indicate  that  the  Interrupt  21H  call  is  a  request  for  a  write 
to  a  device.  The  BX  register  has  the  handle  of  the  device,  1,  which  is  the  special  file  handle 
for  standard  output  istdouf).  For  this  program  as  it  was  invoked,  standard  output  is  the 
screen.  The  CX  register  indicates  that  1  byte  is  to  be  written;  DS:DX  points  to  the  data  to  be 
written.  The  contents  of  memory  at  DS:0F84H  finally  reveal  the  cause  of  the  problem: 

This  memory  location  contains  the  address  of  the  data  to  be  written,  not  the  data.  The 
fputcharO  function  was  called  with  the  wrong  level  of  indirection. 

Examination  of  the  listing  shows  that  all  the  newline  requests  were  made  with 

fputchar ("\n”) ; 

Strings  specified  with  double  quotes  are  replaced  in  C  functions  with  the  address  of  the 
string,  but  the  function  expected  the  actual  character  and  not  its  address.  The  problem  can 
be  corrected  by  replacing  the  fputcharO  calls  with 

fputchar ( ' \n ' ) ; 

The  newline  character  will  now  be  passed  directly  to  the  function. 
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This  kind  of  problem  can  be  avoided.  C  provides  the  ability  to  check  the  type  of  each 
parameter  passed  to  a  function  against  the  expected  type.  If  the  following  definition  is 
included  at  the  top  of  the  C  program,  incorrect  types  will  generate  error  messages: 

#define  LINT_ARGS 

The  corrected  listing  is  shown  in  Figure  18-17.  This  new  program  produces  the  correct 
output. 

/**♦********** ************4:***** ************************* **************** 


*  * 

*  ASCTBL.C  * 

*  This  program  generates  an  ASCII  lookup  table  for  all  displayable  * 

*  ASCII  and  extended  IBM  PC  codes,  leaving  blanks  for  nondisplayable  * 

*  codes .  * 

*  * 


#define  LINT_ARGS 
#include  <ctype.h> 

#include  <stdio.h> 

main  ( ) 

{ 

int  i,  j,  k; 

/*  Print  table  title.  ♦/ 

printf  ("\n\n\n  ASCII  LOOKUP  TABLE\n\n”); 

/*  Print  column  headers.  */ 

printf  ("  "); 

for  (i  =  0;  i  <  16;  i++) 

printf  ('’%X  ”,  i); 

fputchar  ( ' \n ' ) ; 

/*  Print  each  line  of  the  table.  */ 
for  (i  =  0,  k  =  0;  i  <  16;  i++) 

{ 

/*  Print  first  hex  digit  of  symbols  on  this  line.  */ 
printf {”%X  ",  i); 

/*  Print  each  of  the  16  symbols  for  this  line.  */ 
for  (j  =  0;  j  <  16;  j++) 

{ 

/*  Filter  nonprintable  characters.  */ 
if  ((k  >=  7  &&  k  <=  13)  II  (k  >=  28  &&  k  <=  31 )  ) 
printf  (”  "); 

else 

printf (”%c  ”,  k)  ; 

k++; 

} 

fputchar ( ' \n ' ) ; 

} 

} 

Figure  18-1 7.  The  correct  ASCII  table  generation  program. 
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CodeView  is  a  good  choice  for  debugging  C,  Pascal,  BASIC,  and  FORTRAN  programs. 

The  fact  that  versions  of  MASM  earlier  than  5.0  do  not  generate  data  for  CodeView  makes 
CodeView  a  poorer  choice  for  these  assembly-language  programs.  These  disadvantages 
must  be  weighed  against  the  ability  to  set  watchpoints  and  to  trap  nonmaskable  interrupts 
(NMIs).  CodeView  is  also  not  as  well  suited  as  SYMDEB  for  debugging  programs  that  in¬ 
teract  with  TSRs  and  device  drivers,  because  CodeView  does  not  provide  any  mechanism 
for  including  symbol  tables  for  routines  not  linked  together. 

Hardware  debugging  aids 

Hardware  debuggers  are  a  combination  of  hardware  and  software  designed  to  be  installed 
in  a  PC  system.  The  software  provides  features  much  like  those  available  with  SYMDEB 
and  CodeView.  The  advantages  of  hardware  debuggers  over  purely  software  debuggers 
can  be  summarized  in  three  points: 

•  Crash  protection 

•  Manual  execution  break 

•  Hardware  breakpoints 

A  hardware  debugger  can  provide  program  crash  protection  because  of  its  independence 
from  the  PC  software.  If  the  program  being  debugged  goes  wild  and  destroys  the  operat¬ 
ing  system  of  the  PC,  the  hardware  debugger  is  protected  by  virtue  of  being  a  separate 
hardware  system  and  is  capable  of  recovering  enough  control  to  allow  the  user  to  find 
out  what  happened. 

All  hardware  debuggers  offer  a  means  of  breaking  into  the  program  under  test  from  some 
external  source — usually  a  push  button  in  the  hands  of  the  programmer.  The  mechanism 
used  to  get  the  attention  of  the  PC’s  CPU  is  the  nonmaskable  interrupt  (NMI).  This  inter¬ 
rupt  provides  a  more  reliable  means  of  interrupting  program  execution  than  the  Break  key 
because  its  operation  is  independent  of  the  state  of  interrupts  and  other  conditions. 

Hardware  debuggers  usually  have  access  to  the  address  and  data  lines  on  the  PC  bus, 
allowing  them  to  set  hardware  breakpoints.  Thus,  these  debuggers  can  be  set  to  break 
when  specific  addresses  are  referenced.  They  execute  the  breakpoint  code  from  a  debug¬ 
ging  monitor,  which  generally  runs  from  their  own  memory.  This  memory  is  usually 
protected  from  the  regular  operating  system  and  the  application  program. 

Although  hardware  debuggers  can  be  used  to  instrument  a  program,  they  should  not  be 
confused  with  the  external  hardware  instrumentation  discussed  earlier  in  this  article.  The 
logic  analyzers  and  in-circuit  emulators  mentioned  there  are  general-purpose  test  instru¬ 
ments;  the  hardware  debuggers  are  highly  specific  devices  intended  to  do  only  one  thing 
on  one  type  of  hardware — provide  debugging  monitor  functions  at  a  hardware  level  to 
IBM  PC-type  machines.  It  is  this  specialization  that  makes  hardware  debuggers  so  much 
easier  to  use  for  programmers  trying  to  get  a  piece  of  code  running. 

Because  this  volume  deals  only  with  MS-DOS  and  associated  Microsoft  software,  a  detailed 
discussion  of  hardware  debuggers  and  debugging  would  not  be  appropriate.  Instead,  a 
few  popular  hardware  products  that  work  with  MS-DOS  utilities  are  mentioned  and  a  gen¬ 
eral  discussion  of  debugging  with  hardware  is  presented. 
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Several  manufacturers  make  hardware  products  that  can  be  used  for  debugging.  These 
products  vary  in  the  features  offered  and  in  their  suitability  for  various  kinds  of  debugging. 
Three  of  these  products  that  can  be  used  with  SYMDEB  are 

•  IBM  Professional  Debug  Utility 

•  PC  Probe  and  AT  Probe  from  Atron  Corporation 

•  Periscope  from  The  Periscope  Company,  Inc. 

These  boards  can  be  used  with  SYMDEB  by  specifying  the  /N  switch  when  the  program  is 
started.  When  used  in  this  way,  however,  the  hardware  provides  little  more  than  a  source 
of  NMIs  to  interrupt  program  execution;  otherwise,  SYMDEB  runs  as  usual.  This  restric¬ 
tion  may  not  be  acceptable  to  a  programmer  who  wants  to  use  the  sophisticated  debug¬ 
ging  software  that  accompanies  these  products  and  makes  use  of  their  hardware  features. 
For  this  reason,  these  boards  are  rarely  used  with  SYMDEB. 

The  general  techniques  of  debugging  with  hardware  aids  will  already  be  familiar  to  the 
reader — they  are  the  same  techniques  discussed  at  length  earlier  in  this  article.  The  tech¬ 
niques  of  inspection  and  observation  should  still  be  applied;  instrumentation  is  facilitated 
by  hardware;  a  debugging  monitor  accompanies  all  hardware  debuggers  and  the  same 
techniques  discussed  for  DEBUG,  SYMDEB,  and  CodeView  apply.  No  new  techniques  are 
needed  to  use  these  devices.  The  changes  in  the  details  of  the  techniques  come  with  the 
added  features  available  with  the  hardware  debuggers.  (Remember  that  all  these  features 
are  not  universally  available  on  all  hardware  debuggers.) 

The  manual  interrupt  feature  of  hardware  debuggers  is  useful  in  a  system  crash.  Every 
programmer,  especially  assembly-language  programmers,  has  had  the  situation  where  the 
program  runs  wild,  destroys  the  operating  system,  and  locks  up  the  system.  The  tech¬ 
niques  described  in  previous  sections  of  this  article  show  that  about  the  only  way  to  solve 
these  problems  without  hardware  help  is  to  set  breakpoints  at  strategic  locations  in  the 
program  and  see  how  many  are  passed  before  the  system  locks  up.  The  breakpoints  are 
placed  at  finer  and  finer  increments  until  the  instruction  causing  the  crash  is  located. 

This  long  and  ugly  procedure  can  sometimes  be  shortened  with  a  hardware  debugger. 
When  the  system  crashes,  the  programmer  can  push  the  manual  interrupt  button,  suspend 
program  execution,  and  give  control  to  the  debugger  card.  At  this  point,  the  programmer 
can  use  the  debugging  monitor  software  supplied  with  the  card  to  sniff  around  memory 
looking  for  something  suspicious.  Clues  can  sometimes  be  found  by  examining  the  pro¬ 
gram’s  stack  and  data  areas — provided,  of  course,  that  they  are  still  in  memory  and 
haven’t  been  destroyed,  along  with  the  operating  system,  by  the  rampaging  program.  This 
approach  is  not  always  an  immediate  solution  to  the  problem,  however;  often,  the  start- 
and-set-breakpoints  process  has  to  be  repeated  even  with  a  hardware  debugger.  The  hard¬ 
ware  will,  however,  possibly  shed  some  light  on  the  causes  of  the  problem  and  shorten  the 
procedure. 

Another  feature  offered  by  many  of  the  debugging  boards  is  the  ability  to  set  breakpoints 
on  events  other  than  the  execution  of  a  line  of  code.  Often,  these  boards  will  allow  the 
programmer  to  break  on  a  reference  to  a  specific  memory  location,  to  a  range  of  memory 
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locations,  or  to  an  I/O  port.  This  feature  allows  a  watch  to  be  set  on  data,  analogous  to  the 
watchpoint  feature  of  CodeView.  This  technique  is  almost  always  useful,  as  it  is  with 
CodeView,  but  there  is  one  class  of  problems  where  it  is  essential  to  reaching  a  solution. 

Consider  the  case  of  a  program  that  seems  to  be  running  well.  Every  so  often,  however, 
an  ampersand  appears  in  the  middle  of  a  payroll  amount,  or  occasionally  the  program 
makes  an  erroneous  branch  and  executes  the  wrong  path.  Suppose  that,  after  painstaking 
investigation,  the  programmer  discovers  that  these  problems  are  being  caused  by  a  change 
in  a  specific  location  in  memory  sometime  during  the  execution  of  the  program.  In  debug¬ 
ging,  the  discovery  of  the  cause  of  a  problem  usually  leads  almost  instantly  to  a  fix.  Not  so 
in  this  case.  That  byte  of  memory  could  be  changed  by  an  error  in  the  program,  by  a  glitch 
in  the  operating  system  or  in  a  device  driver,  or  by  cosmic  rays  from  outer  space.  Discover¬ 
ing  the  culprit  in  a  case  like  this  is  almost  impossible  without  the  help  of  hardware  break¬ 
points.  Setting  a  breakpoint  on  the  affected  memory  location  and  running  the  program 
will  solve  the  problem.  As  soon  as  the  memory  location  is  changed,  the  breakpoint  will  be 
executed  and  the  state  of  the  system  registers  will  point  a  clear  finger  at  the  instruction 
that  caused  the  problem. 

Hardware  debuggers  can  provide  significant  aid  to  the  serious  programmer.  They  are 
especially  helpful  in  debugging  operating  systems  and  operating-system  services  such  as 
device  drivers.  They  are  also  helpful  in  complicated  situations  where  many  programs  may 
be  running  at  the  same  time.  The  consensus  among  programmers  who  have  hardware 
debuggers  is  that  they  are  well  worth  the  money. 


Summary 

Although  Microsoft  and  others  have  provided  an  impressive  array  of  technology  to  aid 
in  program  debugging,  the  most  important  tool  a  programmer  has  is  his  or  her  native  wit 
and  talent.  As  the  examples  in  this  article  have  illustrated,  the  technology  makes  the  task 
easier,  but  never  easy.  In  all  cases,  however,  it  is  the  programmer  who  debugs  the  program 
and  solves  the  problems. 

Technology  will  never  be  able  to  replace  the  person  for  solving  the  problem  of  a  bug- 
ridden  program.  (This  is  an  area  where  artificial  intelligence  will  undoubtedly  fail.) 
Therefore,  it  is  the  skills  discussed  in  the  first  part  of  this  article — debugging  by  inspec¬ 
tion  and  observation — that  deserve  the  greatest  attention  and  practice.  All  the  other  tech¬ 
niques  and  technologies,  with  their  ever-increasing  sophistication,  are  only  extensions  of 
these  basic  techniques.  A  programmer  who  can  debug  effectively  at  the  lowest  level  of 
technology  will  always  be  ready  to  use  whatever  advanced  technology  is  available. 

Therefore,  as  a  final  word,  remember  the  rule  that  opened  this  article: 

Gather  enough  information  and  the  solution  will  be  obviom. 

All  the  rest  of  this  article  was  merely  a  discussion  of  ways  to  gather  the  information. 


Steve  Bostwick 
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Object  modules  are  used  primarily  by  programmers.  The  end  user  of  an  MS-DOS  appli¬ 
cation  need  never  be  concerned  with  object  code,  object  modules,  and  object  libraries 
because  application  programs  are  almost  always  distributed  as  .EXE  or  .COM  files  that  can 
be  executed  with  a  simple  startup  command. 

An  application  programmer  writing  in  a  high-level  language  can  use  object  modules  and 
object  libraries  without  knowing  either  the  format  of  object  code  or  the  details  of  what  the 
utilities  that  process  object  modules,  such  as  the  Microsoft  Library  Manager  (LIB)  and  the 
Microsoft  Object  Linker  (LINK),  are  actually  doing.  Most  application  programmers  simply 
regard  the  contents  of  an  object  module  as  a  “black  box”  and  trust  their  compilers  and 
object  module  utility  programs  to  do  the  right  thing. 

A  programmer  using  assembly  language  or  an  assembly-language  debugger  such  as 
DEBUG  or  SYMDEB,  however,  might  want  to  know  more  about  the  content  and  function 
of  object  modules.  The  use  of  assembly  language  gives  the  programmer  more  control  over 
the  actual  contents  of  object  modules,  so  knowing  how  the  modules  are  constructed  and 
examining  their  contents  can  sometimes  help  with  program  debugging. 

Finally,  a  programmer  writing  a  compiler,  an  assembler,  or  a  language  translator  must 
know  the  details  of  object  module  format  and  processing.  To  take  advantage  of  LIB  and 
LINK,  a  language  translator  must  construct  object  modules  that  conform  to  the  format  and 
usage  conventions  specified  by  Microsoft. 

Note:  This  article  assumes  some  background  knowledge  of  the  process  by  which  source 
code  is  converted  into  an  executable  file  in  the  MS-DOS  environment.  See  PROGRAM¬ 
MING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Structure  of  an 
Application  Program;  Programming  Tools:  The  Microsoft  Object  Linker;  PROGRAMMING 
UTILITIES. 


The  Use  of  Object  Modules 

Although  some  MS-DOS  language  translators  generate  executable  8086-family  machine 
code  directly  from  source  code,  most  produce  object  code  instead.  Typically,  a  translator 
processes  each  file  of  source  code  individually  and  leaves  the  resulting  object  module 
in  a  separate  file  bearing  a  .OBJ  extension.  The  source-code  files  themselves  remain 
unchanged.  After  all  of  a  program’s  source-code  modules  have  been  translated,  the  result¬ 
ing  object  modules  can  be  linked  into  a  single  executable  program.  Because  object  mod¬ 
ules  frequently  represent  only  a  portion  of  a  complete  program,  each  source-code  module 
usually  contains  instructions  that  indicate  how  its  corresponding  object  code  is  to  be 
combined  with  the  object  code  in  other  object  modules  when  they  are  linked. 
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The  object  code  contained  in  each  object  module  consists  of  a  binary  image  of  the  pro¬ 
gram  plus  program  structure  information.  This  object  code  is  not  directly  executable.  The 
binary  image  corresponds  to  the  executable  code  that  will  ultimately  be  loaded  into  mem¬ 
ory  for  execution;  it  contains  both  machine  code  and  program  data.  The  program  struc¬ 
ture  information  includes  descriptions  of  logical  groupings  defined  in  the  source  code 
(such  as  named  subroutines  or  segments)  and  symbolic  references  to  addresses  in  other 
object  modules. 

The  program  structure  information  is  used  by  a  linkage  editor,  or  linker,  such  as  Microsoft 
LINK  to  edit  the  binary  image  of  the  program  contained  in  the  object  module.  The  linker 
combines  the  binary  images  from  one  or  more  object  modules  into  a  complete  executable 
program. 

The  linker’s  output  is  a  .EXE  file — a  file  containing  executable  machine  code  that  can  be 
loaded  into  RAM  and  executed  (Figure  19-1).  The  linker  leaves  intact  all  of  the  object 
modules  it  processes. 


(Program  runs) 


Figure  19-1.  Generation  of  an  executable  (.EXE)  file. 

Object  code  thus  serves  as  an  intermediate  form  for  compiled  programs.  This  form  offers 

two  major  advantages: 

•  Modular  intermediate  code.  The  use  of  object  modules  eliminates  the  overhead  of 
repeated  compilation  of  an  entire  program  whenever  changes  are  made  to  parts  of  its 
source  code.  Instead,  only  those  object  modules  affected  by  source-code  revisions 
need  be  recompiled. 

•  Shareable  format.  Object  module  format  is  well  defined,  so  object  modules  can  be 
linked  even  if  they  were  produced  by  different  translators.  Many  high-level-language 
compilers  take  advantage  of  this  commonality  of  object-code  format  to  support 
“interlanguage”  linkage. 
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Contents  of  an  object  module 

Object  modules  contain  five  basic  types  of  information.  Some  of  this  information  exists 
explicitly  in  the  source  code  (and  is  subsequently  passed  on  to  the  object  module),  but 
much  is  inferred  by  the  program  translator  from  the  structure  of  the  source  code  and  the 
way  memory  is  accessed  by  the  8086. 

Binary  Image.  As  described  earlier,  the  binary  image  comprises  executable  code  (such  as 
opcodes  and  addresses)  and  program  data.  When  object  modules  are  linked,  the  linker 
builds  an  executable  program  from  the  binary  image  in  each  object  module  it  processes. 
The  binary  image  in  each  object  module  is  always  associated  with  program  structure  in¬ 
formation  that  tells  the  linker  how  to  combine  it  with  related  binary  images  in  other  object 
modules. 

External  References.  Because  an  object  module  generally  represents  only  a  small  portion 
of  a  larger  program  that  will  be  constructed  from  several  object  modules,  it  usually  con¬ 
tains  symbols  that  allow  it  to  be  linked  to  the  other  modules.  Such  references  to  corre¬ 
sponding  symbols  in  other  object  modules  are  resolved  when  the  modules  are  linked. 

For  example,  consider  the  following  short  C  program: 

main  () 


puts ("Hello,  worldXn"); 

} 

This  program  calls  the  C  function  putsQ  to  display  a  character  string,  but  putsQ  is  not 
defined  in  the  source  code.  Rather,  the  name  puts  is  a  reference  to  a  function  that  is  exter¬ 
nal  to  the  program’s  mainQ  routine.  When  the  C  compiler  generates  an  object  module  for 
this  program,  it  will  identify  puts  as  an  external  reference.  Later,  the  linker  will  resolve  the 
external  reference  by  linking  the  object  module  containing  the  putsQ  routine  with  the 
module  containing  the  mainO  routine. 

Address  References.  When  a  program  is  built  from  a  group  of  object  modules,  the  actual 
values  of  many  addresses  cannot  be  computed  until  the  linker  combines  the  binary  image 
of  executable  code  and  the  program  data  from  each  of  the  program’s  constituent  object 
modules.  Object  modules  contain  information  that  tells  the  linker  how  to  resolve  the 
values  of  such  addresses,  either  symbolically  (as  in  the  case  of  external  references)  or  rela¬ 
tively,  in  terms  of  some  other  address  (such  as  the  beginning  of  a  block  of  executable  code 
or  program  data). 

Debugging  Information.  An  object  module  can  also  contain  information  that  relates 
addresses  in  the  executable  program  to  the  corresponding  source  code.  After  the  linker 
performs  its  address  fixups,  it  can  use  the  object  module’s  debugging  information  to  relate 
a  line  of  source  code  in  a  program  module  to  the  executable  code  that  corresponds  to  it. 

Miscellaneous  Information.  Finally,  an  object  module  can  contain  comments,  lists  of 
symbols  defined  in  or  referenced  by  the  module,  module  identification  information,  and 
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information  for  use  by  an  object  library  manager  or  a  linker  (for  example,  the  names  of 
object  libraries  to  be  searched  by  default). 

Object  module  terminology 

When  the  linker  generates  an  executable  program,  it  organizes  the  structural  components 
of  the  program  according  to  the  information  contained  in  the  object  modules.  The  layout 
of  the  executable  program  can  be  conceptually  described  as  a  run-time  memory  map 
after  it  has  been  loaded  into  memory. 

The  basic  structure  of  every  executable  program  for  the  8086  family  of  microprocessors 
must  conform  to  the  segmented  architecture  of  the  microprocessor.  Thus,  the  run-time 
memory  map  of  an  executable  program  is  partitioned  into  segments,  each  of  which  can  be 
addressed  by  using  one  of  the  microprocessor’s  segment  registers.  This  segmented  struc¬ 
ture  of  8086-based  programs  is  the  basis  for  most  of  the  following  terminology. 

Frames.  The  memory  address  space  of  the  8086  is  conceptually  divided  into  a  sequence 
of  paragraph-aligned,  overlapping  64  KB  regions  called  frames.  Frame  0  in  the  8086’s  ad¬ 
dress  space  is  the  64  KB  of  memory  starting  at  physical  address  OOOOOH  (0000:0000  in  seg- 
mentioffset  notation),  frame  1  is  the  64  KB  of  memory  starting  at  OOOlOH  (0001:0000),  and 
so  on.  A  frame  number  thus  denotes  the  beginning  of  any  paragraph-aligned  64  KB  of 
memory.  For  example,  the  location  of  a  64  KB  buffer  that  starts  at  address  B800:0000  can 
be  specified  as  frame  0B800H. 

Logical  Segments.  The  run-time  memory  map  for  every  8086  program  is  partitioned  into 
one  or  more  logical  segments,  which  are  groupings  of  logically  related  portions  of  the  pro¬ 
gram.  Typically,  an  MS-DOS  program  includes  at  least  one  code  segment  (that  contains  all 
of  the  program’s  executable  code),  one  or  more  data  segments  (that  contain  program 
data),  and  one  stack  segment. 

When  a  program  is  loaded  into  RAM  to  be  executed,  each  logical  segment  in  the  program 
can  be  addressed  with  a  frame  number — that  is,  a  physical  8086  segment  address.  Before 
the  MS-DOS  loader  transfers  control  to  a  program  in  memory,  it  initializes  the  CS  and  SS 
registers  with  the  segment  addresses  of  the  program’s  executable  code  and  stack  seg¬ 
ments.  If  an  MS-DOS  program  has  a  separate  logical  segment  for  program  data,  the  pro¬ 
gram  itself  usually  stores  this  segment’s  address  in  the  DS  register. 

Relocatable  Segments.  In  MS-DOS  programs,  most  logical  segments  are  relocatable. 

The  loader  determines  the  physical  addresses  of  a  program’s  relocatable  segments  when 
it  places  the  program  into  memory  to  be  executed.  However,  this  address  determination 
poses  a  problem  for  the  MS-DOS  loader,  because  a  program  may  contain  references  to  the 
address  of  a  relocatable  segment  even  though  the  address  value  is  not  determined  until 
the  program  is  loaded.  The  problem  is  solved  by  indicating  where  such  references  occur 
within  the  program’s  object  modules.  The  linker  then  extracts  this  information  from  the 
object  modules  and  uses  it  to  build  a  list  of  such  address  references  into  a  segment  reloca¬ 
tion  table  in  the  header  of  executable  files.  After  the  loader  copies  a  program  into  memory 
for  execution,  it  uses  the  segment  relocation  table  to  update,  or  fix  up,  the  segment  address 
references  within  the  program. 
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Consider  the  following  example,  in  which  a  program  loads  the  starting  addresses  of  two 
data  segments  into  the  DS  and  ES  segment  registers: 

mov  ax,seg  —DATA 

mov  ds,ax  ;  make  —DATA  segment  addressable  through  DS 

mov  ax, seg  FAR_DATA 

mov  es,ax  ;  make  FAR— DATA  segment  addressable  through  ES 

The  actual  addresses  of  the  _DATA  and  FAR_DATA  segments  are  unknown  when  the 
source  code  is  assembled  and  the  corresponding  object  module  is  constructed.  The  assem¬ 
bler  indicates  this  by  including  segment  fixup  information,  instead  of  actual  segment  ad¬ 
dresses,  in  the  program’s  object  module.  When  the  object  module  is  linked,  the  linker 
builds  this  segment  fixup  information  into  the  segment  relocation  table  in  the  header  of  the 
program’s  .EXE  file.  Then,  when  the  .EXE  file  is  loaded,  the  MS-DOS  loader  uses  the  infor¬ 
mation  in  the  .EXE  file’s  header  to  patch  the  actual  address  values  into  the  program. 

Absolute  Segments.  Sometimes  a  program  needs  to  address  a  predetermined  segment  of 
memory.  In  this  case,  the  program’s  source  code  must  declare  an  absolute  segment  so  that 
a  reference  to  the  corresponding  frame  number  can  be  built  into  the  program’s  object 
module. 

For  example,  a  program  might  need  to  address  a  video  display  buffer  located  at  a  specific 
physical  address.  The  following  assembler  directive  declares  the  name  of  the  segment  and 
its  frame  number: 

VideoBufferSeg  SEGMENT  at  OBSOOh 

Segment  Alignment.  When  a  program  is  loaded,  the  physical  address  of  each  logical  seg¬ 
ment  is  constrained  by  the  segment’s  alignment.  A  segment  can  be  page  aligned  (aligned 
on  a  256-byte  boundary),  paragraph  aligned  (aligned  on  a  l6-byte  paragraph  boundary), 
word  aligned  (aligned  on  an  even-byte  boundary),  or  byte  aligned  (not  aligned  on  any 
particular  boundary).  A  specification  of  each  segment’s  alignment  is  part  of  every  object 
module’s  program  structure  information. 

High-level-language  translators  generally  align  segments  according  to  the  type  of  data 
they  contain.  For  example,  executable  code  segments  are  usually  byte  aligned;  program 
data  segments  are  usually  word  aligned.  With  an  assembler,  segment  alignment  can  be 
specified  with  the  SEGMENT  directive  and  the  assembler  will  build  this  information  into 
the  program’s  object  module. 

Concatenated  Segments.  The  linker  can  concatenate  logical  segments  from  different 
object  modules  when  it  builds  the  executable  program.  For  example,  several  object  mod¬ 
ules  may  each  contain  part  of  a  program’s  executable  code.  When  the  linker  processes 
these  object  modules,  it  can  concatenate  the  executable  code  from  the  different  object 
modules  into  one  range  of  contiguous  addresses. 

The  order  in  which  the  linker  concatenates  logical  segments  in  the  executable  program  is 
determined  by  the  order  in  which  the  linker  processes  its  input  files  and  by  the  program 
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Structure  information  in  the  object  modules.  With  a  high-level-language  translator,  the 
translator  infers  which  segments  can  be  concatenated  from  the  structure  of  the  source 
code  and  builds  appropriate  segment  concatenation  information  into  the  object  modules 
it  generates.  With  an  assembler,  the  segment  class  type  can  be  used  to  indicate  which 
segments  can  be  concatenated. 

Groups  of  Segments.  Segments  with  different  names  may  also  be  grouped  together  by  the 
linker  so  that  they  can  all  be  addressed  within  the  same  64  KB  frame,  even  though  they  are 
not  concatenated.  For  example,  it  might  be  desirable  to  group  program  data  segments  and 
a  stack  segment  within  the  same  64  KB  frame  so  that  program  data  items  and  data  on  the 
stack  can  be  addressed  with  the  same  8086  segment  register. 

In  high-level  languages,  it  is  up  to  the  translator  to  incorporate  appropriate  segment  group¬ 
ing  information  into  the  object  modules  it  generates.  With  an  assembler,  groups  of  seg¬ 
ments  can  be  declared  with  the  GROUP  directive. 

Fixups.  Sometimes  a  compiler  or  an  assembler  encounters  addresses  whose  values  cannot 
be  determined  from  the  source  code.  The  addresses  of  external  symbols  are  an  obvious 
example.  The  addresses  of  relocatable  segments  and  of  labels  within  those  segments  are 
another  example. 

A  fixup  is  a  language  translator’s  way  of  passing  the  buck  about  such  addresses  to  the 
linker.  Typically,  a  translator  builds  a  zero  value  in  the  binary  image  at  locations  where  it 
cannot  store  an  actual  address.  Accompanying  each  such  location  is  fixup  information, 
which  allows  the  linker  to  determine  the  correct  address.  The  linker  then  completes  the 
fixup  by  calculating  the  correct  address  value  and  adding  it  to  the  value  in  the  correspond¬ 
ing  location  in  the  binary  image.  The  only  fixups  the  linker  cannot  fully  resolve  are  those 
that  refer  to  the  segment  address  of  a  relocatable  segment.  Such  addresses  are  not  known 
until  the  program  is  actually  loaded,  so  the  linker,  in  turn,  passes  the  responsibility  to  the 
MS-DOS  loader  by  creating  a  segment  relocation  table  in  the  header  of  the  executable  file. 

To  process  fixups  properly,  the  linker  needs  three  pieces  of  information:  the  LOCATION 
of  the  value  in  the  object  module,  the  nature  of  the  TARGET  (the  address  whose  value  is 
not  yet  known),  and  the  FRAME  in  which  the  address  calculations  are  to  take  place.  Object 
modules  contain  the  LOCATION,  TARGET,  and  FRAME  information  the  linker  uses  to 
calculate  the  appropriate  address  for  any  given  fixup. 

Consider  the  “program”  in  Figure  19-2.  The  statement: 

start:  call  far  ptr  FarProc 

contains  a  reference  to  an  address  in  the  logical  segment  FarSeg2.  Because  the  assembler 
does  not  know  the  address  of  FarSeg2^  it  places  fixup  information  about  the  address  into 
the  object  module.  The  LOCATION  to  be  fixed  up  is  1  byte  past  the  label  start  (the  4-byte 
pointer  following  the  call  opcode  9AH).  The  TARGET  is  the  address  referenced  in  the  call 
instruction — that  is,  the  label  FarProc  in  the  segment  FarSeg2.  The  FRAME  to  which 
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the  fixup  relates  is  designated  by  the  group  FarGroup  and  is  inferred  from  the  statement 

ASSUME  cs: FarGroup 

in  the  FarSeg2  segment. 


title  fixups 


FarGroup  GROUP  FarSegl , FarSeg2 

0000  CodeSeg  SEGMENT  byte  public  'CODE' 

ASSUME  cs: CodeSeg 

0000  9A  0000  -  R  start:  call  far  ptr  FarProc 

0005  CodeSeg  ENDS 


0000 


FarSegl  SEGMENT  byte  public  ;part  of  FarGroup 


0000 


FarSegl  ENDS 


0000  FarSeg2  SEGMENT  byte  public 

ASSUME  cs: FarGroup 

0000  FarProc  PROC  far 

0000  CB  ret  ;a  FAR  return 

FarProc  ENDP 

0001  FarSeg2  ENDS 

END 

Figure  19-2.  A  sample  “program  “  containing  statements  from  which  the  assembler  derives  fixup  information. 

There  are  several  different  ways  for  a  language  translator  to  identify  a  fixup.  For  example, 
the  LOCATION  might  be  a  single  byte,  a  l6-bit  offset,  or  a  32-bit  pointer,  as  in  Figure  19-2. 
The  TARGET  might  be  a  label  whose  offset  is  relative  either  to  the  base  (beginning)  of  a 
particular  segment  or  to  the  LOCATION  itself.  The  FRAME  might  be  a  relocatable  seg¬ 
ment,  an  absolute  segment,  or  a  group  of  segments. 

Taken  together,  all  the  information  in  an  object  module  that  concerns  the  alignment  and 
grouping  of  segments  can  be  regarded  as  a  specification  of  a  program’s  run-time  memory 
map.  In  effect,  the  object  module  specifies  what  goes  where  in  memory  when  a  program 
is  loaded.  The  linker  can  then  take  the  program  structure  information  in  the  object  mod¬ 
ules  and  generate  a  file  containing  an  executable  program  with  the  corresponding 
structure. 
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The  Structure  of  an  Object  Module 

Although  object  modules  contain  the  information  that  ultimately  determines  the  structure 
of  an  executable  program,  they  bear  little  structural  resemblance  to  the  resulting  execut¬ 
able  program.  Each  object  module  is  made  up  of  a  sequence  of  variable-length  object 
records.  Different  types  of  object  records  contain  different  types  of  program  information. 

Each  object  record  begins  with  a  1-byte  field  that  identifies  its  type.  This  is  followed  by  a 
2-byte  field  containing  the  length  (in  bytes)  of  the  remainder  of  the  record.  Next  comes  the 
actual  structural  or  program  information,  represented  in  one  or  more  fields  of  varied 
lengths.  Finally,  each  record  ends  with  a  1-byte  checksum. 

The  sequence  in  which  object  records  appear  in  an  object  module  is  important.  Because 
the  records  vary  in  length,  each  object  module  must  be  constructed  linearly,  from  start  to 
end.  More  important,  however,  is  the  fact  that  some  types  of  object  records  contain  ref¬ 
erences  to  preceding  object  records.  Because  the  linker  processes  object  records  sequen¬ 
tially,  the  position  of  each  object  record  within  an  object  module  depends  primarily  on 
the  type  of  information  each  record  contains. 

Types  of  object  records 

Microsoft  LINK  currently  recognizes  14  types  of  object  records,  each  of  which  carries  a 
specific  type  of  information  within  the  object  module.  Each  type  of  object  record  is 
assigned  an  identifying  six-letter  abbreviation,  but  these  abbrewations  are  used  only  in 
documentation,  not  within  an  object  module  itself.  As  already  mentioned,  the  first  byte 
of  each  object  record  contains  a  value  that  indicates  its  type.  In  a  hexadecimal  dump  of 
the  contents  of  an  object  module,  these  identifying  bytes  identify  the  start  of  each  object 
record. 

Table  19-1  lists  the  types  of  object  records  supported  by  LINK.  The  value  of  each  record’s 
identifying  byte  (in  hexadecimal)  is  included,  along  with  the  six-letter  abbreviation  and  a 
brief  functional  description.  The  functions  of  the  14  types  of  object  records  fall  into  six 
general  categories: 

•  Binary  data  (executable  code  and  program  data)  is  contained  in  the  LEDATA  and 
LIDATA  records. 

•  Address  binding  and  relocation  information  is  contained  in  FIXUPP  records. 

•  The  structure  of  the  run-time  memory  map  is  indicated  by  SEGDEF,  GRPDEF, 
COMDEF,  and  TYPDEF  records. 

•  Symbol  names  are  declared  in  LNAMES,  EXTDEF,  and  PUBDEF  records. 

•  Debugging  information  is  in  the  LINNUM  record. 

•  Finally,  the  structure  of  the  object  module  itself  is  determined  by  the  THEADR, 
COMENT,  and  MODEND  records. 
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Table  19-1.  Types  of 8086  Object  Records  Supported  by  Microsoft  LINK. 


ID  byte  Abbreviation  Description 


80H 

THEADR 

Translator  Header  Record 

88H 

COMENT 

Comment  Record 

8AH 

MODEND 

Module  End  Record 

8CH 

EXTDEF 

External  Names  Definition  Record 

8EH 

TYPDEF 

Type  Definition  Record 

90H 

PUBDEF 

Public  Names  Definition  Record 

94H 

LINNUM 

Line  Number  Record 

96H 

LNAMES 

List  of  Names  Record 

98H 

SEGDEF 

Segment  Definition  Record 

9AH 

GRPDEF 

Group  Definition  Record 

9CH 

FIXUPP 

Fixup  Record 

OAOH 

LEDATA 

Logical  Enumerated  Data  Record 

0A2H 

LIDATA 

Logical  Iterated  Data  Record 

OBOH 

COMDEF 

Communal  Names  Definition  Record 

Object  record  order 

The  sequence  in  which  the  types  of  object  records  appear  in  an  object  module  is  fairly 
flexible  in  some  respects.  Several  record  types  are  optional,  and  if  the  type  of  information 
they  carry  is  unnecessary,  they  are  omitted  from  an  object  module.  In  addition,  most 
object  record  types  can  occur  more  than  once  in  the  same  object  module.  And,  because 
object  records  are  variable  in  length,  it  is  often  possible  to  choose,  as  a  matter  of  conve¬ 
nience,  between  combining  information  into  one  large  record  or  breaking  it  down  into 
several  smaller  records  of  the  same  type. 

As  stated  previously,  an  important  constraint  on  the  order  in  which  object  records  appear 
is  the  need  for  some  types  of  object  records  to  refer  to  information  contained  in  other 
records.  Because  the  linker  processes  the  records  sequentially,  object  records  containing 
such  information  must  precede  the  records  that  refer  to  it.  For  example,  two  types  of  object 
records,  SEGDEF  and  GRPDEF,  refer  to  the  names  contained  in  an  LNAMES  record.  Thus, 
an  LNAMES  record  must  appear  before  any  SEGDEF  or  GRPDEF  records  that  refer  to  it  so 
that  the  names  in  the  LNAMES  record  are  known  to  the  linker  by  the  time  it  processes  the 
SEGDEF  or  GRPDEF  records. 

A  typical  object  module 

Figure  19-3  contains  the  source  code  for  HELLO.ASM,  an  assembly-language  program 
that  displays  a  short  message.  Figure  19-4  is  a  hexadecimal  dump  of  HELLO.OBJ,  the  object 
module  generated  by  assembling  HELLO.ASM  with  the  Microsoft  Macro  Assembler.  Figure 
19-5  isolates  the  object  records  within  the  object  module. 


Section  II:  Programming  in  the  MS-DOS  Environment  65 1 


Part  E:  Programming  Tools 


NAME 

HELLO 

-TEXT 

SEGMENT 

byte  public  'CODE* 

ASSUME 

c  s : -TEXT , ds : -DATA 

Start : 

mov 

ax, seg  msg 

/program  entry  point 

mov 

ds,  ax 

mov 

dx, offset  msg 

/DS:DX  ->  msg 

mov 

ah,09h 

int 

21h 

/perform  int  21 H  function  09H 
/ (Output  character  string) 

mov 

ax, 4C00h 

int 

21h 

/perform  int  21 H  function  4CH 

/ (Terminate  with  return  code) 

-TEXT 

ENDS 

-DATA 

SEGMENT 

word  public  'DATA* 

msg 

DB 

'Hello,  world' , ODh, OAh, ' $ 

-DATA 

ENDS 

-STACK  SEGMENT  stack  'STACK* 

DW  8 Oh  dup(?)  /stack  depth  =  128  words 

-STACK  ENDS 

END  start 

Figure  19-3.  The  source  code  for  HELLO.  ASM. 
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0040 

OF 
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98 
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01 

El 
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0050 
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15 

00 

01 
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B8 

00 

00 

8E 

D8 

BA 

00 
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B4 

09 

0060 

CD 

21 

B8 

00 

4C 

CD 

21 

D5 

9C 

OB 

00 

C8 

01 

04 

02 
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0070 
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06 
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02 

02 

B6 
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13 
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02 
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6C 

6C 

. Hell 
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0090  00  01 

Figure  19-4.  A 

20  77  6F  72  6C  64  OD  OA  24 

01  00  00  AC 

hexadecimal  dump  of  HELLO. OBJ. 

A8 

8A 

07 

00 

Cl 

0, 

world. . $ . 
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.  .C 

0010  4F 

44 

45 

04 

44 

41 

54 

41 

05 

53 

54 

41 

43 

4B 

05 

5F 

ODE. DATA. STACK.- 
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5F 

54 

45 

58 

DATA .  -STACK .  -TEX 

0030  54 

8B 

T. 

SEGDEF 
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98 

07 

00 

28 

11 
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02 

01 

IE 

...  ( . . 

SEGDEF 
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98 

07 

00 

48 

.  .  .H 
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01 

01 

SEGDEF 

0040 

98 
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00 
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01 
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LEDATA 

0050  AO 
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00 

00 
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00 

8E 

D8 

BA 

00 

00 

B4 

09 

0060  CD 

21 

B8 

00 

4C 

CD 

21 

D5 

. ! . .L. ! . 

FIXUPP 

0060 

9C 

OB 

00 

C8 

01 

04 

02 

02 

0070  C4 

06 

04 

02 

02 

B6 

LEDATA 

0070 

AO 

13 

00 

02 

00 

00 

48 

65 

6C 

6C 

. Hell 

0080  6F 

2C 

20 

77 

6F 

72 

6C 

64 

OD 

OA 

24 

A8 

o,  world. . $ . 

MODEND 

0080 

8A 

07 

00 

Cl 

.... 

0090  00 

01 

01 

00 

00 

AC 

Figure  19-5.  The  object  records  in  HELLO.  OBJ. 

As  shown  most  clearly  in  Figure  19-5,  each  of  the  object  records  begins  with  the  single  byte 
value  identifying  the  record’s  type.  The  second  and  third  bytes  of  each  record  contain  a 
single  l6-bit  value,  stored  with  its  low-order  byte  first,  that  represents  the  length  (in  bytes) 
of  the  remainder  of  the  object  record. 

The  first  record,  THEADR,  identifies  the  object  module  and  the  last  record,  MODEND, 
terminates  the  object  module.  The  second  record,  LNAMES,  contains  a  list  of  segment 
names  and  segment  class  names  that  LINK  will  use  to  lay  out  the  run-time  memory  map. 
The  three  succeeding  SEGDEF  records  describe  the  three  corresponding  segments 
defined  in  the  source  code. 
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The  order  in  which  the  object  records  appear  reflects  both  the  structure  of  the  source 
code  and  the  record  order  constraints  already  mentioned.  The  LNAMES  record  appears 
before  the  three  SEGDEF  records  because  each  SEGDEF  record  contains  a  reference  to 
a  name  in  the  LNAMES  record. 

The  binary  data  representing  each  of  the  two  segments  in  the  source  code  is  contained 
in  the  two  LEDATA  records.  The  first  LEDATA  record  represents  the  _TEXT  segment;  the 
second  specifies  the  data  in  the  _DATA  segment.  The  FIXUPP  record  following  the  first 
LEDATA  record  contains  information  about  the  address  references  in  the  _TEXT  segment. 
Again,  the  order  in  which  the  records  appear  is  important:  the  FIXUPP  record  refers  to 
the  LEDATA  record  preceding  it. 

References  between  object  records 

Object  records  can  refer  to  information  in  other  records  either  indirectly,  by  means  of 
implicit  references,  or  directly,  by  means  of  indexed  references  to  names  or  other  records. 

Implicit  References.  Some  types  of  object  records  implicitly  reference  another  record  in 
the  same  object  module.  The  most  important  example  of  such  implicit  referencing  is  in  the 
FIXUPP  record,  which  always  contains  fixup  information  for  the  preceding  LEDATA  or 
LIDATA  record  in  the  object  module.  Whenever  an  LEDATA  or  LIDATA  record  contains  a 
value  that  needs  to  be  fixed  up,  the  next  record  in  the  object  module  is  always  a  FIXUPP 
record  containing  the  actual  fixup  information. 

Indexed  References  to  Names.  An  object  record  that  refers  to  a  symbolic  name,  such  as 
the  name  of  a  segment  or  an  external  routine,  uses  an  index  into  a  list  of  names  contained 
in  a  previous  object  record.  (The  LNAMES  record  in  Figure  19-5  is  an  example.)  The  first 
name  in  such  a  list  has  the  index  number  1,  the  second  name  has  index  number  2,  the  third 
has  index  number  3,  and  so  on.  Altogether,  a  list  of  as  many  as  32,767  (7FFFH)  names  can 
be  incorporated  into  an  object  module — generally  adequate  for  even  the  most  verbose 
programmer.  (LINK  does,  however,  impose  its  own  version-specific  limits.) 

Indexed  References  to  Object  Records.  An  object  record  can  also  refer  to  a  previous 
object  record  by  using  the  same  type  of  index.  In  this  case,  the  index  number  refers  to  one 
of  a  list  of  object  records  of  a  particular  type.  For  example,  a  FIXUPP  record  might  refer  to 
a  segment  by  referencing  one  of  several  preceding  SEGDEF  records  in  the  object  module. 
In  that  case,  a  value  of  1  would  indicate  the  first  SEGDEF  record  in  the  object  module,  a 
value  of  2  would  indicate  the  second,  and  so  on. 

The  index-number  field  in  an  object  record  can  be  either  1  or  2  bytes  long.  If  the  number 
is  in  the  range  0-7FH,  the  high-order  bit  (bit  7)  is  0  and  the  low-order  7  bits  contain  the 
index  number,  so  the  field  is  only  1  byte  long: 


bit 


7  6  5  4  3  2  1  0 


0 


index  number 
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If  the  index  number  is  in  the  range  80-7FFFH,  the  field  is  2  bytes  long.  The  high-order  bit 
of  the  first  byte  in  the  field  is  set  to  1,  and  the  high-order  byte  of  the  index  number  (which 
must  be  in  the  range  0-7FH)  fits  in  the  remaining  7  bits.  The  low-order  byte  of  the  index 
number  is  specified  in  the  second  byte  of  the  field: 


bit 


1 


6 


1 


high-order  byte  of  index  number 


low-order  byte  of  index  number 


first  byte 


second  byte 


The  same  format  is  used  whether  an  index  refers  to  a  list  of  names  or  to  a  previous  object 
record. 


Microsoft  8086  Object  Record  Formats 

Just  as  the  design  of  the  Intel  8086  microprocessor  reflects  the  design  of  its  8-bit  predeces¬ 
sors,  8086  object  record  formats  are  reminiscent  of  the  8-bit  software  tradition.  In  8-bit  sys¬ 
tems,  disk  space  and  RAM  were  often  at  a  premium.  To  minimize  the  space  consumed  by 
object  records,  information  is  packed  into  bit  fields  within  bytes  and  variable-length  fields 
are  frequently  used. 

Microsoft  LINK  recognizes  a  major  subset  of  Intel’s  original  8086  object  module  speci¬ 
fication  (Intel  Technical  Specification  121748-001).  Intel  also  proposed  a  six-letter  name  for 
each  type  of  object  record  and  symbolic  names  for  fields.  These  names  are  documented  in 
the  following  descriptions,  which  appear  in  the  order  shown  earlier  in  Table  19-1. 

The  Intel  record  types  that  are  not  recognized  by  LINK  provide  information  about  an 
executable  program  that  MS-DOS  obtains  in  other  ways.  (For  example,  information  about 
run-time  overlays  is  supplied  in  LINK’S  command  line  rather  than  being  encoded  in  object 
records.)  Because  they  are  ignored  by  LINK,  they  are  not  included  here. 

All  8086  object  records  conform  to  the  following  format: 


- 1 - 

— — 

record 

record 

body 

chk 

type 

length 

sum 

The  record  type  field  is  a  1-byte  field  containing  the  hexadecimal  number  that  identifies 
the  type  of  object  record  isee  Table  19-1). 

The  record  length  is  a  2-byte  field  that  gives  the  length  of  the  remainder  of  the  object 
record  in  bytes  (excluding  the  bytes  in  the  record  type  and  record  length  fields).  The 
record  length  is  stored  with  the  low-order  byte  first. 
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The  body  field  of  the  record  varies  in  size  and  content,  depending  on  the  record  type. 

The  checksum  is  a  1-byte  field  that  contains  the  negative  sum  (modulo  256)  of  all  other 
bytes  in  the  record.  In  other  words,  the  checksum  byte  is  calculated  so  that  the  low-order 
byte  of  the  sum  of  all  the  bytes  in  the  record,  including  the  checksum  byte,  equals  zero. 

Note:  As  shown  in  the  preceding  example,  the  boxes  used  to  depict  the  fields  vary  in  size. 
The  square  boxes  used  for  record  type  and  chksum  indicate  a  single  byte,  the  rectangular 
box  used  for  record  length  indicates  2  bytes,  and  the  diagonal  lines  used  for  body  indicate 
a  variable-length  field. 
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80H  THE  ADR  Translator  Header  Record 

The  THEADR  record  contains  the  name  of  the  object  module.  This  name  identifies  an 
object  module  within  an  object  library  or  in  messages  produced  by  the  linker. 

Record  format 


- 1 - 

- - 

80H 

length 

T-module 

name 

chk 

sum 

- 1 - 

- 7^/.^ - 

T-module  name 

The  T-module  name  field  is  a  variable-length  field  that  contains  the  name  of  the  object 
module.  The  first  byte  of  the  field  contains  the  number  of  subsequent  bytes  that  contain 
the  name  itself  The  name  can  be  uppercase  or  lowercase  and  can  be  any  string  of 
characters. 

The  T-module  name  is  used  by  LIB  and  LINK  within  error  messages.  Language  translators 
frequently  derive  the  T-module  name  from  the  name  of  the  file  that  contains  a  program’s 
source  code.  Assembly-language  programmers  can  specify  the  T-module  name  explicitly 
with  the  assembler  NAME  directive. 

Location  in  object  module 

As  its  name  implies,  the  THEADR  record  must  be  the  first  record  in  every  object  module 
generated  by  a  language  translator. 

Example 

The  following  THEADR  record  was  generated  by  the  Microsoft  C  Compiler: 

01  23456789ABCDEF 

0000  80  09  00  07  68  65  6C  6C  6F  2E  63  CB  _ hello. c. 

•  Byte  OOH  contains  80H,  indicating  a  THEADR  record. 

•  Bytes  01-02H  contain  0009H,  the  length  of  the  remainder  of  the  record. 

•  Bytes  03-0AH  contain  the  T-module  name.  Byte  03H  contains  07H,  the  length  of 
the  name,  and  bytes  04H  through  OAH  contain  the  name  itself  (Jkello.c).  (In  object 
modules  generated  by  the  Microsoft  C  Compiler,  the  THEADR  record  indicates 
the  filename  that  contained  the  C  source  code  for  the  module.) 

•  Byte  OBH  contains  the  checksum,  OCBH. 
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88H  COMENT  Comment  Record 

The  COMENT  record  contains  a  character  string  that  may  represent  a  plain  text  comment, 
a  symbol  meaningful  to  a  program  such  as  LIB  or  LINK,  or  even  binary-encoded  identifica¬ 
tion  data.  An  object  module  can  contain  any  number  of  COMENT  records. 

Record  format 


1 

- - 

88H 

length 

attrib 

com¬ 

ment 

class 

comment 

chk 

sum 

_ 1 _ 

- - 

Attrib 

Attrib  is  a  1-byte  field  in  which  only  the  first  2  bits  are  meaningful: 


bit 

7 

6 

5 

4 

3 

2 

1 

0 

no 

purge 

no 

list 

0 

0 

0 

0 

0 

0 

•  If  bit  7  (no purg^  is  set  to  1,  utility  programs  that  manipulate  object  modules  should 
not  delete  the  comment  record  from  the  object  module.  Bit  7  can  thus  protect  an 
important  comment,  such  as  a  copyright  message,  from  deletion. 

•  If  bit  6  (no  list)  is  set  to  1,  utility  programs  that  can  list  the  contents  of  object  modules 
are  directed  not  to  list  the  comment.  Bit  6  can  thus  hide  a  comment. 

•  Bits  5  through  0  are  unused  and  should  be  set  to  0. 

Microsoft  LIB  ignores  the  attrib  field. 

Comment  class 

Comment  class  is  a  1-byte  field  whose  value  provides  information  about  the  type  of 
comment.  The  original  Intel  specification  provided  for  the  following  possible  comment 
class  values: 


Value  Use 

OOH  Language-translator  comment  (the  name  of  the  translator  that  generated  the 

object  module). 

OlH  Copyright  comment. 

02-9BH  Reserved  for  Intel  proprietary  software. 
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Microsoft  language  translators  can  generate  several  other  classes  of  COMENT  record  that 
communicate  specific  information  about  the  object  module  to  LINK: 


Value  Use 

81H  Obsolete;  replaced  by  comment  class  9FH. 

9CH  MS-DOS  version  number.  Some  language  translators  create  a  COMENT  record 
with  a  2-byte  binary  value  in  the  comment  field  indicating  the  MS-DOS  ver¬ 
sion  under  which  the  module  was  created.  This  record  is  ignored  by  LINK. 

9DH  Memory  model.  The  comment  field  contains  a  string  that  indicates  the  mem¬ 
ory  model  used  by  the  language  translator.  The  string  contains  one  of  the 
lowercase  letters  s,  c,  m,  1,  and  h  to  designate  small,  compact,  medium,  large, 
and  huge  memory  models.  Microsoft  language  translators  generate  COMENT 
records  with  this  comment  class  only  for  compatibility  with  the  XENIX  ver¬ 
sion  of  LINK.  The  MS-DOS  version  of  LINK  ignores  these  COMENT  records. 

9EH  Sets  Microsoft  LINK’S  DOSSEG  switch. 

9FH  Default  library  search  name.  LINK  interprets  the  contents  of  the  comment 

field  as  the  name  of  a  library  to  be  searched  in  order  to  resolve  external  ref¬ 
erences  within  the  object  module.  The  default  library  search  can  be  overrid¬ 
den  with  LINK’S  NODEFAULTLIBRARYSEARCH  switch. 

OAIH  Indicates  that  Microsoft  extensions  to  the  Intel  object  record  specification  are 

used  in  the  object  module.  For  example,  when  COMDEF  records  are  used 
within  an  object  module,  a  COMENT  record  with  comment  class  OAIH  must 
appear  in  the  object  module  at  some  point  before  the  first  COMDEF  record. 
LINK  ignores  the  comment  string  in  COMENT  records  with  this  comment 
class. 

OCOH-  Reserved  for  user-defined  comment  classes. 

OFFH 

Comment 

The  comment  field  is  a  variable-length  string  of  bytes  that  represent  the  comment.  The 

length  of  the  string  is  inferred  from  the  length  of  the  object  record. 

Location  in  object  module 

A  COMENT  record  can  appear  almost  anywhere  in  an  object  module.  Only  two  restric¬ 
tions  apply: 

•  A  COMENT  record  cannot  be  placed  between  a  FIXUPP  record  and  the  LEDATA  or 
LIDATA  record  to  which  it  refers. 

•  A  COMENT  record  cannot  be  the  first  or  last  record  in  an  object  module.  (The  first 
record  must  always  be  a  THEADR  record  and  the  last  must  always  be  MODEND.) 
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Examples 

The  following  three  examples  are  typical  COMENT  records  taken  from  an  object  module 
generated  by  the  Microsoft  C  Compiler. 

This  first  example  is  a  language-translator  comment: 

01  23456789ABCDEF 

0000  88  07  00  00  00  4D  53  20  43  6E  . MS  Cn 

•  Byte  OOH  contains  88H,  indicating  that  this  is  a  COMENT  record. 

•  Bytes  01-02H  contain  0007H,  the  length  of  the  remainder  of  the  record. 

•  Byte  03H  (the  attrib  field)  contains  OOH.  Bit  7  (wo purge)  is  set  to  0,  indicating  that 
this  COMENT  record  may  be  purged  from  the  object  module  by  a  utility  program  that 
manipulates  object  modules.  Bit  6  (wo  list)  is  set  to  0,  indicating  that  this  comment 
need  not  be  excluded  from  any  listing  of  the  module’s  contents.  The  remaining  bits 
are  all  0. 

•  Byte  04H  (the  comment  class  field)  contains  OOH,  indicating  that  this  COMENT  record 
contains  the  name  of  the  language  translator  that  generated  the  object  module. 

•  Bytes  05H  through  08H  contain  the  name  of  the  language  translator,  MS  C. 

•  Byte  09H  contains  the  checksum,  6EH. 

The  second  example  contains  the  name  of  an  object  library  to  be  searched  by  default 
when  LINK  processes  the  object  module  containing  this  COMENT  record: 

01  23456789ABCDEF 

0000  88  09  00  00  9F  53  4C  49  42  46  50  10  . SLIBFP. 

•  Byte  04H  (the  comment  class  field)  contains  9FH,  indicating  that  this  record  contains 
the  name  of  a  library  for  LINK  to  use  to  resolve  external  references. 

•  Bytes  05-0AH  contain  the  library  name,  SLIBFP.  In  this  example,  the  name  refers  to 
the  Microsoft  C  Compiler’s  floating-point  function  library,  SLIBFP.LIB. 

The  last  example  indicates  that  the  object  module  contains  Microsoft-defined  extensions  to 
the  Intel  object  module  specification: 

01  23456789ABCDEF 

0000  88  06  00  00  A1  01  43  56  37  . CV7 

•  Byte  04H  indicates  the  comment  class,  OAIH. 

•  Bytes  05-07H,  which  contain  the  comment  string,  are  ignored  by  LINK. 
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8AH  MODEND  Module  End  Record 


The  MODEND  record  denotes  the  end  of  an  object  module.  It  also  indicates  whether  the 
object  module  contains  the  main  routine  in  a  program,  and  it  can,  optionally,  contain  a 
reference  to  a  program’s  entry  point. 

Record  format 


- 1 - 

- - 

8AH 

length 

module 

type 

Start  address 

chk 

sum 

1 

- - 

Module  type 

The  module  type  field  is  an  8-bit  (1-byte)  field: 


bit 

7 

6 

5 

4 

3 

2 

1 

0 

main 

start 

0 

0 

0 

0 

0 

1 

•  Bit  7  (jnairi)  is  set  to  1  if  the  module  is  a  main  program  module. 

•  Bit  6  (.start)  is  set  to  1  if  the  MODEND  record  contains  an  entry  point  (start  address). 

•  Bit  0  is  set  to  1  if  the  start  address  field  contains  a  relocatable  address  reference  that 
LINK  must  fix  up.  If  bit  6  is  set  to  1,  bit  0  must  also  be  set  to  1.  (The  Intel  specification 
allows  bit  0  to  be  set  to  0,  to  indicate  that  start  address  is  an  absolute  physical  address, 
but  this  capability  is  not  supported  by  LINK.) 

Start  address 

The  start  address  field  appears  in  the  MODEND  record  only  when  bit  6  is  set  to  1: 


- - 

- - 

- - 

end 

dat 

frame  datum 

target  datum 

target 

displacement 

— — - 

- - 

— — 

The  format  and  interpretation  of  the  start  address  field  corresponds  to  the  fixup  field 
of  the  FIXUPP  record.  The  end  dat  field  corresponds  to  the  fix  dat  field  in  the  FIXUPP 
record.  Bit  2  of  the  end  dat  field,  which  corresponds  to  the  P  bit  in  a  fix  dat  field,  must 
be  zero. 

Location  in  object  module 

A  MOE)END  record  can  appear  only  as  the  last  record  in  an  object  module. 
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Example 

Consider  the  MODEND  record  of  the  HELLO.ASM  example: 

01  23456789ABCDEF 

0000  8A  07  00  Cl  00  01  01  00  00  AC  . 

•  Byte  OOH  contains  8AH,  indicating  a  MODEND  record. 

•  Bytes  01-02H  contain  0007H,  the  length  of  the  remainder  of  the  record. 

•  Byte  03H  contains  OCIH  (IIOOOOOIB).  Bit  7  is  set  to  1,  indicating  that  this  module  is 
the  main  module  of  the  program.  Bit  6  is  set  to  1,  indicating  that  a  start  address  field  is 
present.  Bit  0  is  set  to  1,  indicating  that  the  address  referenced  in  the  start  address 
field  must  be  fixed  up  by  LINK. 

•  Byte  04H  iend  dat  in  the  start  address  field)  contains  OOH.  As  in  a  FIXUPP  record, 
bit  7  indicates  that  the  frame  for  this  fixup  is  specified  explicitly,  and  bits  6  through  4 
indicate  that  a  SEGDEF  index  specifies  the  frame.  Bit  3  indicates  that  the  target  refer¬ 
ence  is  also  specified  explicitly,  and  bits  2  through  0  indicate  that  a  SEGDEF  index 
also  specifies  the  target.  See  also  FIXUPP  9CH  Fixup  Record  below. 

•  Byte  05H  i  frame  datum  in  the  start  address  field)  contains  OlH.  This  is  a  reference 
to  the  first  SEGDEF  record  in  the  module,  which  in  this  example  corresponds  to  the 
^TEXT  segment.  This  reference  tells  LINK  that  the  start  address  lies  in  the  ^TEXT 
segment  of  the  module. 

•  Byte  06H  (target  datum  in  the  start  address  field)  contains  OlH.  This  too  is  a  ref¬ 
erence  to  the  first  SEGDEF  record  in  the  object  module,  which  corresponds  to  the 
_TEXT  segment.  LINK  uses  the  following  target  displacement  field  to  determine 
where  in  the  ^TEXT  segment  the  address  lies. 

•  Bytes  07-08H  (target  displacement  in  the  start  address  field)  contain  OOOOH.  This  is 
the  offset  (in  bytes)  of  the  start  address. 

•  Byte  09H  contains  the  checksum,  OACH. 
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8CH  EXTDEF  External  Names  Definition  Record 

The  EXTDEF  record  contains  a  list  of  symbolic  external  references — that  is,  references  to 
symbols  defined  in  other  object  modules.  The  linker  resolves  external  references  by 
matching  the  symbols  declared  in  EXTDEF  records  with  symbols  declared  in  PUBDEF 
records. 

Record  format 


1 

- - 

chk 

sum 

8CH 

length 

_ 1 _ 

external  reference  list 

- -J 

^can  be-^ 
repeated 


External  reference  list 

The  external  reference  list  is  a  variable-length  field  containing  a  list  of  names  and  name 
types,  each  formatted  as  follows: 


- - 

name 

length 

name 

type 

index 

- - 

•  The  name  length  is  a  1-byte  field  containing  the  length  of  the  name  field  that  follows 
it.  (LINK  restricts  name  length  to  a  value  between  OlH  and  7FH.) 

•  The  type  index  is  a  1-byte  reference  to  the  TYPDEF  record  in  the  object  module  that 
describes  the  type  of  symbol  the  name  represents.  A  type  index  value  of  zero  indi¬ 
cates  that  no  TYPDEF  record  is  associated  with  the  symbol.  A  nonzero  value  indicates 
which  TYPDEF  record  is  associated  with  the  external  name.  Microsoft  LINK  recog¬ 
nizes  TYPDEF  records  only  for  the  purpose  of  declaring  communal  variables.  See  8EH 
TYPDEF  Type  Definition  Record  below. 

LINK  imposes  a  limit  of  1023  external  names. 

Location  in  object  module 

Any  EXTDEF  records  in  an  object  module  must  appear  before  the  FIXUPP  records  that 

reference  them.  Also,  if  an  EXTDEF  record  contains  a  nonzero  type  index,  the  indexed 

TYPDEF  record  must  precede  the  EXTDEF  record. 

Example 

Consider  this  EXTDEF  record  generated  by  the  Microsoft  C  Compiler: 


0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0000 

8C 

25 

00 

OA 

5F 

5F 

61 

63 

72 

74 

75 

73 

65 

64 

00 

05 

.  % _ _ acrtused.  . 

0010 

5F 

6D 

61 

69 

6E 

00 

05 

5F 

70 

75 

74 

73 

00 

08 

5F 

5F 

—main. .—puts. - 

0020 

63 

68 

6B 

73 

74 

6B 

00 

A5 

chkstk. . 
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•  Byte  OOH  contains  8CH,  indicating  that  this  is  an  EXTDEF  record. 

•  Bytes  01-02H  contain  0025H,  the  length  of  the  remainder  of  the  record. 

•  Bytes  03-26H  contain  a  list  of  external  references.  The  first  reference  starts  in  byte 

03H,  which  contains  OAH,  the  length  of  the  name acrtused.  The  name  itself  fol¬ 
lows  in  bytes  04-0DH.  Byte  OEH  contains  OOH,  which  indicates  that  the  symbol’s  type 
is  not  defined  by  any  TYPDEF  record  in  this  object  module.  Bytes  0F-26H  contain 
similar  references  to  the  external  symbols  _^main,  ^puts,  and _ chkstk 

•  Byte  27H  contains  the  checksum,  0A5H. 
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8EH  T  YPDEF  Type  Definition  Record 

The  TYPDEF  record  contains  details  about  the  type  of  data  represented  by  a  name 
declared  in  a  PUBDEF  or  an  EXTDEF  record.  This  information  may  be  used  by  the  linker 
to  validate  references  to  names,  or  it  may  be  used  by  a  debugger  to  display  data  according 
to  type. 

Starting  with  Microsoft  LINK  version  3.50,  the  COMDEF  record  should  be  used  for  declara¬ 
tion  of  communal  variables.  For  compatibility,  however,  later  versions  of  LINK  recognize 
TYPDEF  records  as  well  as  COMDEF  records. 

Record  format 


8EH 

length 

« 

name 

- - 

eight-leaf 
descriptor 
^-—///- — 

chk 

sum 

can  be  y 
repeated 


Although  the  original  Intel  specification  allowed  for  many  different  type  specifications, 
such  as  scalar,  pointer,  and  mixed  data  structure,  LINK  uses  TYPDEF  records  to  declare 
only  communal  variables.  Communal  variables  represent  globally  shared  memory  areas — 
for  example,  FORTRAN  common  blocks  or  uninitialized  public  variables  in  C. 

The  size  of  a  communal  variable  is  declared  explicitly  in  the  TYPDEF  record.  If  a 
communal  variable  has  different  sizes  in  different  object  modules,  LINK  uses  the  largest 
declared  size  when  it  generates  an  executable  module. 

Name 


The  name  field  of  a  TYPDEF  record  is  a  1-byte  field  that  is  always  null;  that  is,  it  contains  a 
single  zero  byte. 

Eight-leaf  descriptor 

The  eight-leaf  descriptor  field,  in  the  original  Intel  specification,  was  a  variable-length 
field  that  contained  as  many  as  eight  “leaves”  that  could  be  used  to  describe  mixed  data 
structures. 

Microsoft  uses  a  stripped-down  version  of  the  eight-leaf  descriptor,  because  the  field’s  only 
function  is  to  describe  communal  variables: 


- - 

0 

leaf  descriptor 

can  be 
repeated 
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•  The  first  field  in  the  eight-leaf  descriptor  is  a  1-byte  field  that  contains  a  zero  byte. 

•  The  leaf  descriptor  field  is  a  variable-length  field  that  is  itself  divided  into  four  fields 
(“leaves”)  that  describe  the  size  and  type  of  a  variable.  The  two  possible  variable 
types  are  NEAR  and  FAR. 

If  the  field  describes  a  NEAR  variable  (one  that  can  be  referenced  as  an  offset  within  a 
default  data  segment),  the  format  is 


62H 

variable 

type 

- - 

length  in  bits 

- - 

-  The  1-byte  field  containing  62H  signifies  a  NEAR  variable. 

-  The  variable  type  field  is  a  1-byte  field  that  specifies  the  variable  type: 

77H  Array 

79H  Structure 

7BH  Scalar 

This  field  is  ignored  by  LINK. 

-  The  length  in  bits  field  is  a  variable-length  field  that  indicates  the  size  of  the  com¬ 
munal  variable.  Its  format  depends  on  the  size  it  represents.  If  the  size  is  less  than 
128  (80H)  bits,  length  in  bits  is  a  1-byte  field  containing  the  actual  size  of  the  field: 


If  the  size  is  128  bits  or  greater,  it  cannot  be  represented  in  a  single  byte  value,  so 
the  length  in  bits  field  is  formatted  with  an  extra  initial  byte  that  indicates  whether 
the  size  is  represented  as  a  2-,  3-,  or  4-byte  value: 
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If  the  leaf  descriptor  field  describes  a  FAR  variable  (one  that  must  be  referenced  with 
an  explicit  segment  and  offset),  the  format  is 


- tO/ - 

- - 

61 H 

variable 

number  of 

element  type 

type 

elements 

index 

- - 

- - 

-  The  1-byte  field  containing  6lH  signifies  a  FAR  variable. 

-  The  1-byte  variable  type  for  a  FAR  communal  variable  is  restricted  to  77H  (array). 
(As  with  the  NEAR  variable  type  field,  LINK  ignores  this  field.) 

-  The  number  of  elements  is  a  variable-length  field  that  contains  the  number  of 
elements  in  the  array.  It  has  the  same  format  as  the  length  in  bits  field  in  the  leaf 
descriptor  for  a  NEAR  variable. 

-  The  element  type  index  is  an  index  field  that  references  a  previous  TYPDEF 
record.  A  value  of  1  indicates  the  first  TYPDEF  record  in  the  object  module,  a  value 
of  2  indicates  the  second  TYPDEF  record,  and  so  on.  The  TYPDEF  record  refer¬ 
enced  must  describe  a  NEAR  variable.  This  way,  the  data  type  and  size  of  the 
elements  in  the  array  can  be  determined. 

Location  in  object  module 

Any  TYPDEF  records  in  an  object  module  must  precede  the  EXTDEF  or  PUBDEF  records 
that  reference  them. 

Examples 

The  following  three  examples  of  TYPDEF  records  were  generated  by  the  Microsoft  C 
Compiler  version  3.0.  (Later  versions  use  COMDEF  records.) 

The  first  sample  TYPDEF  record  corresponds  to  the  public  declaration 

int  foo;  /*  16-bit  integer  */ 

The  TYPEDEF  record  is 

01  23456789ABCDEF 

0000  8E  06  00  00  00  62  7B  1 0  7F  . b{ . . 

•  Byte  OOH  contains  8EH,  indicating  that  this  is  a  TYPDEF  record. 

•  Bytes  01-02H  contain  0006H,  the  length  of  the  remainder  of  the  record. 

•  Byte  03H  (the  name  field)  contains  OOH,  a  null  name. 

•  Bytes  04-07H  represent  the  eight-leaf  descriptor  field.  The  first  byte  of  this  field 
(byte  04H)  contains  OOH.  The  remaining  bytes  (bytes  05-07H)  represent  the  leaf 
descriptorfield: 

-  Byte  05H  contains  62H,  indicating  this  TYPDEF  record  describes  a  NEAR  variable. 

-  Byte  06H  (the  variable  type  field)  contains  7BH,  which  describes  this  variable  as 
a  scalar. 

-  Byte  07H  (the  length  in  bits  field)  contains  lOH,  the  size  of  the  variable  in  bits. 
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•  Byte  OSH  contains  the  checksum,  7FH. 

The  next  example  demonstrates  how  the  variable  size  contained  in  the  length  in  bits  field 
of  the  leaf  descriptor  is  formatted: 

char  foo2 [32768];  /*  32  KB  array  */ 

01  23456789ABCDEF 

0000  8E  09  00  00  00  62  7B  84  00  00  04  04  . b{ . 

•  The  length  in  bits  field  (bytes  07-0AH)  starts  with  a  byte  containing  84H,  which  in¬ 
dicates  that  the  actual  size  of  the  variable  is  represented  as  a  3-byte  value  (the  follow¬ 
ing  3  bytes).  Bytes  08-0AH  contain  the  value  040000H,  the  size  of  the  32  KB  array 

in  bits. 

This  third  C  statement,  because  it  declares  a  FAR  variable,  causes  two  TYPDEF  records  to 
be  generated: 

char  far  foo3[10]  [2]  [20];  /*  400-element  FAR  array  */ 

The  two  TYPDEF  records  are 

01  23456789ABCDEF 

0000  8E  06  00  00  00  62  7B  08  87  8E  09  00  00  00  61  77  . b{ . aw 

0010  81  90  01  01  7E  . . . .  | 

•  Bytes  00-08H  contain  the  first  TYPDEF  record,  which  defines  the  data  type  of  the 
elements  of  the  array  (NEAR,  scalar,  8  bits  in  size). 

•  Bytes  09-14H  contain  the  second  TYPDEF  record.  The  leaf  descriptor  field  of  this 
record  declares  that  the  variable  is  FAR  (byte  OEH  contains  6lH)  and  an  array  (byte 
OFH,  the  variable  type,  contains  77H). 

-  Because  this  TYPDEF  record  describes  a  FAR  variable,  bytes  10-12H  represent 
a  number  of  elements  field.  The  first  byte  of  the  field  is  81H,  indicating  a  2-byte 
value,  so  the  next  2  bytes  (bytes  11-12H)  contain  the  number  of  elements  in  the 
array,  0190H  (400D). 

•  Byte  13H  (the  element  type  indeoi)  contains  OlH,  which  is  a  reference  to  the  first 
TYPDEF  record  in  the  object  module — in  this  example,  the  one  in  bytes  00-08H. 
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90H  PUBDEF  Public  Names  Definition  Record 

The  PUBDEF  record  contains  a  list  of  public  names.  When  object  modules  are  linked,  the 
linker  uses  these  names  to  resolve  external  references  in  other  object  modules. 

Record  format 


- 1 - 

- - 

- - 

public 

offset 

- - 

90H 

length 

public  base 

public  name 

type  index 

chk 

sum 

_ 1 - 

- - 

- 

- —///—^ 

-can  be  - 
repeated 


Public  base 

Each  name  in  the  PUBDEF  record  refers  to  a  location  (a  l6-bit  offset)  in  a  particular  seg¬ 
ment  or  group.  The  public  base,  a  variable-length  field  that  specifies  the  segment  or  group, 
is  formatted  as  follows: 


- - 

- - 

1 

frame 

number 

group  index 

segment  index 

- - 

- - 

_ i - 

•  Group  index  is  an  index  field  that  references  a  previous  GRPDEF  record  in  the  object 
module.  If  the  group  index  value  is  0,  no  group  is  associated  with  this  PUBDEF 
record. 

•  Segment  index  is  also  an  index  field.  It  associates  a  particular  segment  with  this 
PUBDEF  record  by  referencing  a  previous  SEGDEF  record.  A  value  of  1  indicates  the 
first  SEGDEF  record  in  the  object  module,  a  value  of  2  indicates  the  second,  and  so  on. 
If  the  segment  index  value  is  0,  the  group  index  must  also  be  0 — in  this  case,  the 
frame  number  appears  in  the  public  base  field. 

•  The  2-byte  frame  number  appears  in  the  public  base  field  only  when  the  group 
index  and  segment  index  are  both  0.  In  other  words,  the  frame  number  specifies 
the  start  of  an  absolute  segment.  If  present,  the  value  in  the  frame  number  field  indi¬ 
cates  the  number  of  the  frame  containing  the  public  name. 

Public  name 

Public  name  is  a  variable-length  field  containing  a  public  name.  The  first  byte  specifies 
the  length  of  the  name;  the  remainder  is  the  name  itself.  (The  Intel  specification  allows 
names  of  1  to  255  bytes.  Microsoft  LINK  restricts  the  maximum  length  of  a  public  name  to 
127  bytes.) 
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Public  offset 

Public  offset  is  a  2-byte  field  containing  the  offset  of  the  location  referred  to  by  the  public 
name.  This  offset  is  assumed  to  lie  within  the  segment,  group,  or  frame  specified  in  the 
public  base  field. 

Type  index 

Type  index  is  an  index  field  that  references  a  previous  TYPDEF  record  in  the  object  mod¬ 
ule.  A  value  of  1  indicates  the  first  TYPDEF  record  in  the  module,  a  value  of  2  indicates  the 
second,  and  so  on.  The  type  index  value  can  be  0  if  no  data  type  is  associated  with  the 
public  name. 

The  public  name,  public  offset,  and  type  index  fields  can  be  repeated  within  a  single 
PUBDEF  record.  Thus,  one  PUBDEF  record  can  declare  a  list  of  public  names. 

Location  in  object  module 

Any  PUBDEF  records  in  an  object  module  must  appear  after  the  GRPDEF  and  SEGDEF 
records  to  which  they  refer.  Because  PUBDEF  records  are  not  themselves  referenced  by 
any  other  type  of  object  record,  they  are  generally  placed  near  the  end  of  an  object 
module. 

Examples 

The  following  two  examples  show  PUBDEF  records  created  by  the  Microsoft  Macro 
Assembler. 

The  first  example  is  the  record  for  the  statement 

PUBLIC  GAMMA 

The  PUBDEF  record  is 

01  23456789ABCDEF 

0000  90  OC  00  00  01  05  47  41  4D  4D  41  02  00  00  F9  . GAMMA _ 

•  Byte  OOH  contains  90H,  indicating  a  PUBDEF  record. 

•  Bytes  01-02H  contain  OOOCH,  the  length  of  the  remainder  of  the  record. 

•  Bytes  03-04H  represent  the  public  base  field.  Byte  03H  (the  group  index)  contains  0, 
indicating  that  no  group  is  associated  with  the  name  in  this  PUBDEF  record.  Byte  04H 
(the  segment  indeoc)  contains  1,  a  reference  to  the  first  SEGDEF  record  in  the  object 
module.  This  is  the  segment  to  which  the  name  in  this  PUBDEF  record  refers. 

•  Bytes  05-0AH  represent  the  public  name  field.  Byte  05H  contains  05H  (the  length  of 
the  name),  and  bytes  O6-OAH  contain  the  name  itself,  GAMMA. 

•  Bytes  OB-OCH  contain  0002H,  the  public  offset.  The  name  GAMMA  thus  refers  to  the 
location  that  is  offset  2  bytes  from  the  beginning  of  the  segment  referenced  by  the 
public  base. 

•  Byte  ODH  is  the  type  index.  The  value  of  the  type  index  is  0,  indicating  that  no  data 
type  is  associated  with  the  name  GAMMA. 

•  Byte  OEH  contains  the  checksum,  0F9H. 
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The  next  example  is  the  PUBDEF  record  for  the  following  absolute  symbol  declaration: 

PUBLIC  ALPHA 

ALPHA  EQU  1234h 

The  PUBDEF  record  is 

01  23456789ABCDEF 

0000  90  OE  00  00  00  00  00  05  41  4C  50  48  41  34  12  00  . ALPHA4 _ 

0010  B1 

•  Bytes  03-06H  (the public  base  field)  contain  a  group  index  of  0  (byte  03H)  and  a 
segment  index  of  0  (byte  04H).  Since  both  the  group  index  and  segment  index  are  0, 
a  frame  number  also  appears  in  the  public  base  field.  In  this  instance,  the  frame 
number  (bytes  05-06H)  also  happens  to  be  0. 

•  Bytes  07-0CH  (the  public  name  field)  contain  the  name  ALPHA,  preceded  by  its 
length. 

•  Bytes  OD-OEH  (the  public  offset  field)  contain  1234H.  This  is  the  value  associated 
with  the  symbol  ALPHA  in  the  assembler  EQU  directive.  If  ALPHA  is  declared  in 
another  object  module  with  the  declaration 

EXTRN  ALPHA :ABS 

any  references  to  ALPHA  in  that  object  module  are  fixed  up  as  absolute  references  to 
offset  1234H  in  frame  0.  In  other  words,  ALPHA  would  have  the  value  1234H. 

•  Byte  OFH  (the  type  index)  contains  0. 
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94H  LINNUM  line  Number  Record 

The  LINNUM  record  relates  line  numbers  in  source  code  to  addresses  in  object  code. 

Record  format 


94H 


length 


line  number 
base 


number 


line  number 
offset 


chk 

sum 


^can  be^ 
repeated 


Line  number  base 

The  line  number  base  describes  the  segment  to  which  the  line  number  refers.  Although 
the  complete  Intel  specification  allows  the  line  number  base  to  refer  to  a  group  or  to  an 
absolute  segment  as  well  as  to  a  relocatable  segment,  Microsoft  restricts  references  in  this 
field  to  relocatable  segments.  The  format  of  the  line  number  base  field  is 


- - 

group 

index 

segment  index 

- - 

•  The  group  index  field  always  contains  a  single  zero  byte. 

•  The  segment  index  is  an  index  field  that  references  a  previous  SEGDEF  record.  A 
value  of  1  indicates  the  first  SEGDEF  record  in  the  object  module,  a  value  of  2  indicates 
the  second,  and  so  on. 

line  number 

Line  number  is  a  2-byte  field  containing  a  line  number  between  0  and  32,767 
(0-7FFFH). 

line  number  offset 

The  line  number  offset  is  a  2-byte  field  that  specifies  the  offset  of  the  executable  code  (in 
the  segment  specified  in  the  line  number  base  field)  to  which  the  line  number  in  the  line 
number  field  refers. 

The  line  number  and  line  number  offset  fields  can  be  repeated,  so  a  single  LINNUM 
record  can  specify  multiple  line  numbers  in  the  same  segment. 

Location  in  object  module 

Any  LINNUM  records  in  an  object  module  must  appear  after  the  SEGDEF  records  to  which 
they  refer.  Because  LINNUM  records  are  not  themselves  referenced  by  any  other  type  of 
object  record,  they  are  generally  placed  near  the  end  of  an  object  module. 
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Example 

The  following  LINNUM  record  was  generated  by  the  Microsoft  C  Compiler: 

01  23456789ABCDEF 

0000  94  OF  00  00  01  02  00  00  00  03  00  08  00  04  00  OF  . 

0010  00  3C 

•  Byte  OOH  contains  94H,  indicating  that  this  is  a  LINNUM  record. 

•  Bytes  01-02H  contain  OOOFH,  the  length  of  the  remainder  of  the  record. 

•  Bytes  03-04H  represent  the  line  number  base  field.  Byte  03H  (the  group  index  field) 
contains  OOH,  as  it  must.  Byte  04H  (the  segment  index  field)  contains  OlH,  indicating 
that  the  line  numbers  in  this  LINNUM  record  refer  to  code  in  the  segment  defined  in 
the  first  SEGDEF  record  in  this  object  module. 

•  Bytes  05-'06H  (a  line  number  field)  contain  0002H,  and  bytes  07-08H  (a  line  num¬ 
ber  offset  field)  contain  OOOOH.  Together,  they  indicate  that  source-code  line  number 
0002  corresponds  to  offset  OOOOH  in  the  segment  indicated  in  the  line  number  base 
field. 

Similarly,  the  two  pairs  of  line  number  and  line  number  offset  fields  in  bytes  09-lOH 
specify  that  line  number  0003  corresponds  to  offset  0008H  and  that  line  number  0004 
corresponds  to  offset  OOOFH. 

•  Byte  IIH  contains  the  checksum,  3CH. 
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96H  LNAMES  List  of  Names  Record 

The  LNAMES  record  is  a  list  of  names  that  can  be  referenced  by  subsequent  SEGDEF  and 
GRPDEF  records  in  the  object  module. 

Record  format 


96H 

length 

- - 

name  list 

chk 

sum 

_ 1 _ 

- 5 

s.can  be  ^ 
repeated 


Name  list 

Name  list  is  a  variable-length  field  that  contains  the  list  of  names.  Each  name  is  preceded 
by  1  byte  that  defines  its  length,  which  can  be  a  value  between  0  and  255  (O-OFFH). 

The  names  in  the  list  are  indexed  implicitly  in  the  order  they  appear:  The  first  name  in  the 
list  has  an  index  of  1,  the  second  name  has  an  index  of  2,  and  so  forth.  References  to  the 
names  contained  in  name  list  by  subsequent  object  records,  such  as  SEGDEF,  are  accom¬ 
plished  by  using  this  index  number.  LINK  imposes  a  limit  of  255  logical  names  per  object 
module. 

Location  in  object  module 

Any  LNAMES  records  in  an  object  module  must  appear  before  the  GRPDEF  or  SEGDEF 
records  that  refer  to  them.  Because  it  does  not  refer  to  any  other  type  of  object  records,  an 
LNAMES  record  usually  appears  near  the  start  of  an  object  module. 

Example 

The  following  LNAMES  record  contains  the  segment  and  class  names  specified  in  all  three 
of  the  assembler  statements: 

-TEXT  SEGMENT  byte  public  »CODE* 

-DATA  SEGMENT  word  public  'DATA* 

-STACK  SEGMENT  para  public  'STACK' 

The  LNAMES  record  is 

01  23456789ABCDEF 

0000  96  25  00  00  04  43  4F  44  45  04  44  41  54  41  05  53  .%.. .CODE .DATA. S 

0010  54  41  43  4B  05  5F  44  41  54  41  06  5F  53  54  41  43  TACK. -DATA. -STAC 

0020  4B  05  5F  54  45  58  54  8B  K.-TEXT. 

•  Byte  OOH  contains  96H,  indicating  that  this  is  an  LNAMES  record. 

•  Bytes  01-02H  contain  0025H,  the  length  of  the  remainder  of  the  record. 
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•  Byte  03H  contains  OOH,  a  zero-length  name. 

•  Byte  04H  contains  04H,  the  length  of  the  class  name  CODE,  which  is  found  in  bytes 
05-08H.  Bytes  09-26H  contain  the  class  names  DATA  and  STACK  and  the  segment 
names  ^DATA,  _STACK,  and  _TEXT,  each  preceded  by  1  byte  giving  its  length. 

•  Byte  27H  contains  the  checksum,  8BH. 
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98H  SEGDEF  Segment  Definition  Record 

The  SEGDEF  record  describes  a  logical  segment  in  an  object  module.  It  defines  the  seg¬ 
ment’s  name,  length,  and  alignment,  and  the  way  the  segment  can  be  combined  with  other 
logical  segments.  LINK  imposes  a  limit  of  255  SEGDEF  records  per  object  module. 

Object  records  that  follow  a  SEGDEF  record  can  refer  to  it  to  identify  a  particular  segment. 

Record  format 


98H 


length 


segment 

attributes 


segment 

length 


segment  name 
index 


classi  name 
index 


overlay  name 
index 


chk 

sum 


Segment  attributes 

Segment  attributes  is  a  variable-length  field: 


acbp  frame 
byte  number 


offset 


The  ACBP  byte 

The  contents  and  size  of  the  segment  attributes  field  depend  on  the  first  byte  of  the  field, 
the  ACBP  byte: 

bit  7  6  5  4  3  2  1  0 


A 

C 

B 

P 

The  bit  fields  in  the  ACBP  byte  describe  the  following  characteristics  of  the  segment: 

A  Alignment  in  the  run-time  memory  map 
C  Combination  with  other  segments 
B  Big  (a  segment  of  exactly  64  KB) 

P  Page-resident  (not  used  in  MS-DOS) 


The  A  field.  Bits  7-5  of  the  ACBP  byte,  the  A  field,  describe  the  logical  segment’s 
alignment: 


A  =  0(000B) 
^=1(001B) 
.^=2(010B) 
^  =  3(011B) 
^  =  4  (lOOB) 


Absolute  (located  at  a  specified  frame  address) 
Relocatable,  byte  aligned 
Relocatable,  word  aligned 
Relocatable,  paragraph  aligned 
Relocatable,  page  aligned 
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The  original  Intel  specification  includes  two  additional  segment-alignment  values  not 
supported  in  MS-DOS. 

The  following  examples  of  Microsoft  assembler  SEGMENT  directives  show  the  resulting 
values  for  the  A  field  in  the  corresponding  SEGDEF  object  record: 

aseg  SEGMENT  at  400h  ;  A  =  0 

bseg  SEGMENT  byte  public  'CODE*  ;  A  =  1 

cseg  SEGMENT  para  stack  'STACK'  ;  A  =  3 

The  C field.  Bits  4-2  of  the  ACBP  byte,  the  C  field,  describe  how  the  linker  can  combine 
the  segment  with  other  segments.  Under  MS-DOS,  segments  with  the  same  name  and  class 
can  be  combined  in  two  ways.  They  can  be  concatenated  to  form  one  logical  segment,  or 
they  can  be  overlapped.  In  the  latter  case,  they  have  either  the  same  starting  address  or  the 
same  end  address  and  they  describe  a  common  area  of  memory. 

The  value  in  the  C  field  corresponds  to  one  of  these  two  methods  of  combining  segments. 
Meaningful  values,  however,  also  depend  on  whether  the  segment  is  absolute  (A  =  0)  or 
relocatable  (A  =  1,  2,  3,  or  4).  If  A  =  0,  then  C  must  also  be  0,  because  absolute  segments 
cannot  be  combined.  Values  for  the  C  field  are 


c:=0(000B) 

C=  1  (OOIB) 
C7=2(010B) 

6’=3(011B) 
6’=4(100B) 
5  (lOlB) 

6*=  6  (HOB) 

C=7(111B) 


Cannot  be  combined;  used  for  segments  whose  combine  type  is  not 
explicitly  specified  (private  segments). 

Not  used  by  Microsoft. 

Can  be  concatenated  with  another  segment  of  the  same  name;  used  for 
segments  with  the  public  combine  type. 

Undefined. 

As  defined  by  Microsoft,  same  as  C  =  2. 

Can  be  concatenated  with  another  segment  with  the  same  name;  used  for 
segments  with  the  stack  combine  type. 

Can  be  overlapped  with  another  segment  with  the  same  name;  used  for 
segments  with  the  common  combine  type. 

As  defined  by  Microsoft,  same  as  C  =  2. 


The  following  examples  of  assembler  SEGMENT  directives  show  the  resulting  values  for 
the  C  field  in  the  corresponding  SEGDEF  object  record: 


aseg 

SEGMENT 

at  400H 

;  c  = 

bseg 

SEGMENT 

public 

'  DATA ' 

;  c  = 

cseg 

SEGMENT 

stack  ' 

STACK' 

;  c  = 

dseg 

SEGMENT 

common 

'  COMMON ' 

;  c  = 

See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  Tools:  The 
Microsoft  Object  Linker. 

The  B  and  P fields.  Bit  1  of  the  ACBP  byte,  the  B  field,  is  set  to  1  (and  the  segment  length 
field  is  set  to  0)  only  if  the  segment  is  exactly  64  KB  long. 

Bit  0  of  the  ACBP  byte,  the  P  field,  is  unused  in  MS-DOS.  Its  value  should  always  be  0. 
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Frame  number  and  offset 

The  frame  number  and  offset  fields  of  the  segment  attributes  field  are  present  only  if  the 
segment  is  an  absolute  segment  (A  =  0  in  the  ACBP  byte).  Taken  together,  the  frame  num¬ 
ber  and  offset  indicate  the  starting  address  of  the  segment. 

•  Frame  number  is  a  2-byte  field  that  contains  the  frame  number  of  the  start  of  the 
segment. 

•  Offset  is  a  l-byte  field  that  contains  an  offset  between  OOH  and  OFH  within  the  speci¬ 
fied  frame.  LINK  ignores  the  offset  field. 

Segment  length 

Segment  length  is  a  2-byte  field  that  specifies  the  length  of  the  segment  in  bytes.  The 
length  can  be  from  OOH  to  FFFFH.  If  a  segment  is  exactly  64  KB  (lOOOOH)  in  size,  segment 
length  should  be  0  and  the  Afield  in  the  ACBP  byte  should  be  1. 

Segment  name  index,  class  name  index,  and  overlay  name  index 

Each  of  the  segment  name  index,  class  name  index,  and  overlay  name  index  fields 
contains  an  index  into  the  list  of  names  defined  in  previous  LNAMES  records  in  the  object 
module.  An  index  value  of  1  indicates  the  first  name  in  the  LNAMES  record,  a  value  of  2  the 
second,  and  so  on. 

•  The  segment  name  index  identifies  the  segment  with  a  unique  name.  The  name  may 
have  been  assigned  by  the  programmer,  or  it  may  have  been  generated  by  a  compiler. 

•  The  class  name  index  identifies  the  segment  with  a  class  name  (such  as  CODE, 
FAR^DATA,  and  STACK).  The  linker  places  segments  with  the  same  class  name  into 
a  contiguous  area  of  memory  in  the  run-time  memory  map. 

•  The  overlay  name  index  identifies  the  segment  with  a  run-time  overlay.  Starting  with 
version  2.40,  however,  LINK  ignores  the  overlay  name  index.  In  versions  2.40  and 
later,  command-line  parameters  to  LINK,  rather  than  information  contained  in  object 
modules,  determine  the  creation  of  run-time  overlays. 

Location  in  object  module 

SEGDEF  records  must  follow  the  LNAMES  record  to  which  they  refer.  In  addition,  SEGDEF 
records  must  precede  any  PUBDEF,  LINNUM,  GRPDEF,  FIXUPP,  LEDATA,  or  LIDATA 
records  that  refer  to  them. 

Examples 

In  this  first  example,  the  segment  is  byte  aligned: 

0123456789ABCDEF 
0000  98  07  00  28  11  00  07  02  01  1E  ...( . 

•  Byte  OOH  contains  98H,  indicating  that  this  is  a  SEGDEF  record. 

•  Bytes  01-02H  contain  0007H,  the  length  of  the  remainder  of  the  record. 
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•  Byte  03H  contains  28H  (OOlOlOOOB),  the  ACBP  byte.  Bits  7-5  (the  A  field)  contain  1 
(OOIB),  indicating  that  this  segment  is  relocatable  and  byte  aligned.  Bits  4-2  (the  C 
field)  contain  2  (OlOB),  which  represents  a  public  combine  type.  (When  this  object 
module  is  linked,  this  segment  will  be  concatenated  with  all  other  segments  with  the 
same  name.)  Bit  1  (the  B  field)  is  0,  indicating  that  this  segment  is  smaller  than  64  KB. 
Bit  0  (the  P  field)  is  ignored  and  should  be  zero,  as  it  is  here. 

•  Bytes  04-05H  contain  OOllH,  the  size  of  the  segment  in  bytes. 

•  Bytes  06-08H  index  the  list  of  names  defined  in  the  module’s  LNAMES  record.  Byte 
06H  (jhe  segment  name  indeoc)  contains  07H,  so  the  name  of  this  segment  is  the 
seventh  name  in  the  LNAMES  record.  Byte  07H  (the  class  name  indeoi)  contains  02H, 
so  the  segment’s  class  name  is  the  second  name  in  the  LNAMES  record.  Byte  08H  (the 
overlay  name  indeod  contains  1,  a  reference  to  the  first  name  in  the  LNAMES  record. 
(This  name  is  usually  null,  as  MS-DOS  ignores  it  anyway.) 

•  Byte  09H  contains  the  checksum,  lEH. 

The  second  SEGDEF  record  declares  a  word-aligned  segment.  It  differs  only  slightly  from 

the  first. 

01  23456789ABCDEF 

0000  98  07  00  48  OF  00  05  03  01  01  ...H . 

•  Bits  7-5  (the  A  field)  of  byte  03H  (the  ACBP  byte)  contain  2  (OlOB),  indicating  that 
this  segment  is  relocatable  and  word  aligned. 

•  Bytes  04-05H  contain  the  size  of  the  segment,  OOOFH. 

•  Byte  06H  (the  segment  name  index)  contains  05H,  which  refers  to  the  fifth  name  in 
the  previous  LNAMES  record. 

•  Byte  07H  (the  class  name  index)  contains  03H,  a  reference  to  the  third  name  in  the 
LNAMES  record. 
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9AH  GRPDEF  Group  Definition  Record 

The  GRPDEF  record  defines  a  group  of  segments,  all  of  which  lie  within  the  same  64  KB 
frame  in  the  run-time  memory  map.  LINK  imposes  a  limit  of  21  GRPDEF  records  per 
object  module. 

Record  format 


9AH 

length 

_ 1 _ 

- - 

group  name 
index 

- - 

- - 

group  component 
descriptor 

L  V//  J 

chk 

sum 

^can  be 
repeated 


Group  name  index 

Group  name  index  is  an  index  field  whose  value  refers  to  a  name  in  the  name  list  field  of 
a  previous  LNAMES  record. 

Group  component  descriptor 

The  group  component  descriptor  consists  of  two  fields: 


- - 

type 

segment  index 

- - 

•  Type  is  a  1-byte  field  whose  value  is  always  OFFH,  indicating  that  the  following  field 
contains  a  segment  index  value.  The  original  Intel  specification  defines  four  other 
types  of  group  component  descriptor  with  the  values  OFEH,  OFDH,  OFBH,  and  OFAH. 
LINK  ignores  these  other  type  values,  however,  and  assumes  that  the  group  compo¬ 
nent  descriptor  contains  a  segment  index  value. 

•  The  segment  index  field  contains  an  index  number  that  refers  to  a  previous  SEGDEF 
record.  A  value  of  1  indicates  the  first  SEGDEF  record  in  the  object  module,  a  value  of 
2  indicates  the  second,  and  so  on. 

The  group  component  descriptor  field  is  usually  repeated  within  the  GRPDEF  record,  so 
all  segments  constituting  the  group  can  be  included  in  one  GRPDEF  record. 

Location  in  object  module 

GRPDEF  records  must  follow  the  LNAMES  and  SEGDEF  records  to  which  they  refer.  They 
must  also  precede  any  PUBDEF,  LINNUM,  FIXUPP,  LEDATA,  or  LIDATA  records  that  refer 
to  them. 
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Example 

The  following  example  of  a  GRPDEF  record  corresponds  to  the  assembler  directive; 

tgroup  GROUP  segl , seg2 , seg3 

The  GRPDEF  record  is 

01  23456789ABCDEF 

0000  9A  08  00  06  FF  01  FF  02  FF  03  55  . U 

•  Byte  OOH  contains  9AH,  indicating  that  this  is  a  GRPDEF  record. 

•  Bytes  01~02H  contain  0008H,  the  length  of  the  remainder  of  the  record. 

•  Byte  03H  contains  06H,  the  group  name  index.  In  this  instance,  the  index  number 
refers  to  the  sixth  name  in  the  previous  LNAMES  record  in  the  object  module.  That 
name  is  the  name  of  the  group  of  segments  defined  in  the  remainder  of  the  record. 

•  Bytes  04-05H  contain  the  first  of  three  group  component  descriptor  fields.  Byte  04H 
contains  the  required  OFFH,  indicating  that  the  subsequent  field  is  a  segment  index. 
Byte  05H  contains  OlH,  a  segment  index  that  refers  to  the  first  SEGDEF  record  in  the 
object  module.  This  SEGDEF  record  declared  the  first  of  three  segments  in  the  group. 

•  Bytes  06-07H  represent  the  second  group  component  descriptor,  this  one  referring  to 
the  second  SEGDEF  record  in  the  object  module. 

•  Similarly,  bytes  08-09H  are  a  group  component  descriptor  field  that  references  the 
third  SEGDEF  record. 

•  Byte  OAH  contains  the  checksum,  55H. 
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9CH  FIXUPP  Fixup  Record 

The  FIXUPP  record  contains  information  that  allows  the  linker  to  resolve  (fix  up)  ad¬ 
dresses  whose  values  cannot  be  determined  by  the  language  translator.  FIXUPP  records 
describe  the  LOCATION  of  each  address  value  to  be  fixed  up,  the  TARGET  address  to 
which  the  fixup  refers,  and  the  FRAME  relative  to  which  the  address  computation  is 
performed. 

Record  format 


- 1 - 

- - 

- - 

chk 

sum 

9CH 

length 

thread 

fixup 

- 1 - 

7 

^can  be 
repeated 


.can  be  / 
repeated 


Thread  and  fixup  fields 

A  FIXUPP  record  can  contain  zero  or  more  thread  fields  and  zero  or  more  fixup  fields. 
Each  fiocup  field  describes  the  method  to  be  used  by  the  linker  to  compute  the  TARGET 
address  to  be  placed  at  a  particular  location  in  the  executable  image,  relative  to  a  particular 
FRAME.  The  information  that  determines  the  LOCATION,  TARGET,  and  FRAME  can  b^ 
specified  explicitly  in  the  fixup  field.  It  can  also  be  specified  within  the  fixup  field  by  a 
reference  to  a  previous  thread  field. 

A  thread  field  describes  only  the  method  to  be  used  by  the  linker  to  refer  to  a  particular 
TARGET  or  FRAME.  Because  the  same  thread  field  can  be  referenced  in  several  subse¬ 
quent  fixup  fields,  a  FIXUPP  record  that  uses  thread  fields  may  be  smaller  than  one  in 
which  thread  fields  are  not  used. 

Thread  and  fiocup  fields  are  distinguished  from  one  another  by  the  high-order  bit  of  the 
first  byte  in  the  field.  If  the  high-order  bit  is  0,  the  field  is  a  thread  field.  If  the  high-order 
bit  is  1,  the  field  is  a  fiocup  field. 

The  thread  field 

A  thread  field  contains  information  that  can  be  referenced  in  subsequent  thread  or  fiocup 
fields  in  the  same  or  subsequent  FIXUPP  records.  It  has  the  following  format: 


- - 

thread 

data 

index 

- - 
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The  thread  data  field  is  a  single  byte  comprising  five  subfields: 


bit 

7 

6 

5 

4  3  2 

1  0 

0 

D 

0 

method 

thread 

number 

•  Bit  7  of  the  thread  data  byte  is  0,  indicating  the  start  of  a  thread  field. 

•  The  D  field  (bit  6)  indicates  whether  the  thread  field  specifies  a  FRAME  or  a 
TARGET.  The  D  bit  is  set  to  1  to  indicate  a  FRAME  or  to  0  to  indicate  a  TARGET. 

•  Bit  5  of  the  thread  data  byte  is  not  used.  It  should  always  be  set  to  0. 

•  Bits  4  through  2  represent  the  method  field.  If  D  =  1,  the  method  field  contains  0, 1,  2, 
4,  or  5.  Each  of  these  numbers  corresponds  to  one  method  of  specifying  a  FRAME  isee 
Table  19-2).  If  Z)  =  0,  the  method  field  contains  0, 1,  2, 4,  5,  or  6,  each  of  which  corre¬ 
sponds  to  one  of  the  methods  of  specifying  a  TARGET  isee  Table  19-3). 

In  the  case  of  a  TARGET  address,  only  bits  3  and  2  of  the  method  field  are  used.  When 
Z)  =  0,  the  high-order  bit  of  the  value  in  the  method  field  is  derived  from  the  P  bit  in 
the  fix  dat  field  of  any  subsequent  fixup  field  that  refers  to  this  thread  field.  Thus,  if 
£)  =  0,  bit  4  of  the  method  field  is  also  0,  and  the  only  meaningful  values  for  the 
method  field  are  0, 1,  and  2. 

•  The  thread  number  field  (bits  1  and  0)  contains  a  number  between  0  and  3.  This 
number  is  used  in  subsequent  fiocup  or  thread  fields  to  refer  to  this  particular  thread 
field. 

The  thread  number  is  implicitly  associated  with  the  D  field  by  the  linker,  so  as  many 
as  eight  different  thread  fields  (four  FRAMES  and  four  TARGETS)  can  be  referenced  at 
any  time.  A  thread  number  can  be  reused  in  an  object  module  and,  if  it  is,  always 
refers  to  the  thread  field  in  which  it  last  appeared. 

Table  19-2.  FRAME  Fixup  Methods. 

Method  Description 

0  The  FRAME  is  specified  by  a  segment  index. 

1  The  FRAME  is  specified  by  a  group  index. 

2  The  FRAME  is  indicated  by  an  external  index.  LINK  determines  the  FRAME 

from  the  external  name’s  corresponding  PUBDEF  record  in  another  object 

module,  which  specifies  either  a  logical  segment  or  a  group. 

3  The  FRAME  is  identified  by  an  explicit  frame  number.  (Not  supported  by 

LINK.) 

4  The  FRAME  is  determined  by  the  segment  in  which  the  LOCATION  is  defined. 

In  this  case,  the  largest  possible  frame  number  is  used. 

5  The  FRAME  is  determined  by  the  TARGET’S  segment,  group,  or  external 

index. 
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Table  19-3-  TARGET  Fixup  Methods. 


Method  Description 

0  The  TARGET  is  specified  by  a  segment  index  and  a  displacement.  The 

displacement  is  given  in  the  target  displacement  field  of  the  FIXUPP  record. 

1  The  TARGET  is  specified  by  a  group  index  and  a  target  displacement. 

2  The  TARGET  is  specified  by  an  external  index  and  a  target  displacement. 

LINK  adds  the  displacement  to  the  address  it  determines  from  the  external 
name’s  corresponding  PUBDEF  record  in  another  object  module. 

3  The  TARGET  is  identified  by  an  explicit  frame  number.  (Not  supported  by 

LINK.) 

4  *  The  TARGET  is  specified  by  a  segment  index  only. 

5  *  The  TARGET  is  specified  by  a  group  index  only. 

6*  The  TARGET  is  specified  by  an  external  index.  The  TARGET  is  the  address 

associated  with  the  external  name. 

7  *  The  TARGET  is  identified  by  an  explicit  frame  number.  (Not  supported  by 

LINK.) 


*  TARGET  methods  4-7  are  analogous  to  the  preceding  four,  except  that  methods  4-7  do  not  use  an  explicit 
displacement  to  identify  the  TARGET.  Instead,  a  displacement  of  0  is  assumed. 

The  index  field  either  contains  an  index  value  that  refers  to  a  previous  SEGDEF,  GRPDEF, 
or  EXTDEF  record,  or  it  contains  an  explicit  frame  number.  The  interpretation  of  the  index 
value  depends  on  the  value  of  the  method  field  of  the  thread  data  field: 

method  =  0  Segment  index  (reference  to  a  previous  SEGDEF  record) 
method  =  1  Group  index  (reference  to  a  previous  GRPDEF  record) 
method  =  2  External  index  (reference  to  a  previous  EXTDEF  record) 
method  =  3  Frame  number  (not  supported  by  LINK;  ignored) 

The  fixup  field 

The  fiocup  field  provides  the  information  needed  by  the  linker  to  resolve  a  reference  to  a 
relocatable  or  external  address.  The  fixup  field  has  the  following  format: 


- 1 - 

- /C// - 

- - 

- 1 - 

locat 

fix 

dat 

frame  datum 

target  datum 

target 

displacement 

_ 1 _ 

- /// - 

- - 

- 1 - 

The  2-byte  locat  field  has  an  unusual  format.  Contrary  to  the  usual  byte  order  in  Intel  data 
structures,  the  most  significant  bits  of  the  locat  field  are  found  in  the  low-order,  rather  than 
the  high-order,  byte: 


low-order  byte  high-order  byte 


15 

14 

13 

12  11  10 

9  8 

7  6  5  4  3  2  1  0 

1 

M 

S 

ioc 

_ 1 

data  record  offset 

1 
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•  Bit  15  (the  high-order  bit  of  the  locat  field)  contains  1,  indicating  that  this  is  a  fixup 
field. 

•  Bit  14  (the  M  bit)  is  1  if  the  fixup  is  sclent  relative  and  0  if  the  fixup  is  self-relative. 

•  Bit  13  (the  S  bit)  is  currently  unused  and  should  always  be  set  to  0. 

•  Bits  12  through  10  represent  the  loc  field.  This  field  contains  a  number  between  0  and 
5  that  indicates  the  type  of  LOCATION  to  be  fixed  up: 


loc  =  0 

Low-order  byte 

loc  =  1 

Offset 

loc  =  2 

Segment 

loc  =  5 

Pointer  (segmentioffset) 

loc  =  4: 

High-order  byte  (not  recognized  by  LINK) 

loc  =  5 

Loader-resolved  offset  (treated  as  loc  =  1  by  the  linker) 

•  Bits  9  through  0  (the  data  record  offset)  indicate  the  position  of  the  LOCATION  to  be 
fixed  up  in  the  LEDATA  or  LIDATA  record  immediately  preceding  the  FIXUPP  record. 
This  offset  indicates  either  a  byte  in  the  data  field  of  an  LEDATA  record  or  a  data  byte 
in  the  content  field  of  an  iterated  data  block  in  an  LIDATA  record. 

The  fix  dot  field  is  a  single  byte  comprising  five  fields: 


bit 

7 

6  5  4 

3 

2 

1  0 

F 

frame 

T 

P 

targt 

•  Bit  7  (the  F  bit)  is  set  to  1  if  the  FRAME  for  this  fixup  is  specified  by  a  reference  to  a 
previous  thread  field.  The  F  bit  is  0  if  the  FRAME  method  is  explicitly  defined  in  this 
fixup  field. 

•  The  interpretation  of  the  frame  field  in  bits  6  through  4  depends  on  the  value  of  the 
F  bit.  If  F  =  1,  the  frame  field  contains  a  number  between  0  and  3  that  indicates  the 
thread  field  containing  the  FRAME  method.  If  F=  0,  the  frame  field  contains  0, 1,  2, 
4,  or  5,  corresponding  to  one  of  the  methods  of  specifying  a  FRAME  listed  in  Table 
19-2. 

•  Bit  3  (the  T  bit)  is  set  to  1  if  the  TARGET  for  the  fixup  is  specified  by  a  reference  to  a 
previous  thread  field.  If  the  T  bit  is  0,  the  TARGET  is  explicitly  defined  in  this  fixup 
field. 

•  Bit  2  (the  P  bit)  and  bits  1  and  0  (the  targt  field)  can  be  considered  a  3-bit  field  analo¬ 
gous  to  the  frame  field. 

•  If  the  T  bit  indicates  that  the  TARGET  is  specified  by  a  previous  thread  reference 
(r  =  1),  the  targt  field  contains  a  nvimber  between  0  and  3  that  refers  to  a  previous 
thread  field  containing  the  TARGET  method.  In  this  case,  the  P  bit,  combined  with 
the  2  low-order  bits  of  the  method  field  in  the  thread  field,  determines  the  TARGET 
method. 
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If  the  T  bit  is  0,  indicating  that  the  target  is  explicitly  defined,  the  P  and  targt  fields 
together  contain  0, 1,  2, 4, 5,  or  6.  This  number  corresponds  to  one  of  the  TARGET 
fixup  methods  listed  in  Table  19-3.  (In  this  case,  the  P  bit  can  be  regarded  as  the 
high-order  bit  of  the  method  number.) 

Frame  datum  is  an  index  field  that  refers  to  a  previous  SEGDEF,  GRPDEF,  or  EXTDEF 
record,  depending  on  the  FRAME  method. 

Similarly,  the  target  datum  field  contains  a  segment  index,  a  group  index,  or  an  external 
index,  depending  on  the  TARGET  method. 

The  target  displacement  field,  a  2-byte  field,  is  present  only  if  the  P  bit  in  the  fixdat  field 
is  set  to  0,  in  which  case  the  target  displacement  field  contains  the  l6-bit  offset  used  in 
methods  0, 1,  and  2  of  specifying  a  TARGET. 

Location  in  object  module 

FIXUPP  records  must  appear  after  the  SEGDEF,  GRPDEF,  or  EXTDEF  records  to  which 
they  refer.  In  addition,  if  a  FIXUPP  record  contains  any  fixup  fields,  it  must  immediately 
follow  the  LEDATA  or  LIDATA  record  to  which  the  fixups  refer. 

Examples 

Although  crucial  to  the  proper  linking  of  object  modules,  FIXUPP  records  are  terse: 

Almost  every  bit  is  meanin^ul.  For  these  reasons,  the  following  three  examples  of  FIXUPP 
records  are  particularly  detailed. 

A  good  way  to  understand  how  a  FIXUPP  record  is  put  together  is  to  compare  it  to  the  cor¬ 
responding  source  code.  The  Microsoft  Macro  Assembler  is  helpful  in  this  regard,  because 
it  marks  in  its  source  listing  address  references  it  cannot  resolve.  The  “program”  in  Figure 
19-6  is  designed  to  show  how  some  of  the  most  frequently  encountered  fixups  are  encoded 
in  FIXUPP  records. 


TITLE 

f ixupps 

_TEXT  SEGMENT 

byte  public  'CODE' 

ASSUME 

cs:_TEXT 

EXTRN 

NearLabel : near 

EXTRN 

FarLabel : far 

0000 

NearProc 

PROC  near 

0000 

E9 

0000 

E 

jmp 

NearLabel  ; relocatable 

word  offset 

0003 

EB 

00  E 

jmp 

short  NearLabel  /relocatable 

byte  offset 

0005 

EA 

0000 

- R 

jmp 

far  ptr  FarProc  /far  jump  to 

a  known  seg 

OOOA 

EA 

0000 

- E 

jmp 

FarLabel  / far  jump  to  an 

unknown  seg 

OOOF 

BB 

0015 

R 

mov 

bx, offset  LocalLabel  /relocatable  offset 

0012 

B8 

— 

R 

mov 

ax,seg  LocalLabel  /relocatable  seg 

Figure  19-6.  A  sample  "program  ’  ’  showing  how  some  common  fixups  are  encoded  in  FIXUPP  records .  (more) 
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0015  C3  LocalLabel:  ret 

NearProc  ENDP 

0016  -TEXT  ENDS 


0000  FAR_TEXT  SEGMENT  byte  public  'FAR_C0DE' 

ASSUME  cs : FAR_TEXT 

0000  FarProc  PROC  far 

0000  CB  ret 

FarProc  ENDP 

0001  FAR-TEXT  ENDS 

END 

Figure  19-6.  Continued. 

The  assembler  generates  one  LEDATA  record  for  this  program: 

01  2345678  9  ABCDEF 

0010  AO  1 A  00  01  00  00  E9  00  00  EB  00  EA  00  00  00  00  . 

0020  EA  00  00  00  00  BB  00  00  B8  00  00  C3  67  . g 

Bytes  06-2BH  (the  data  field)  of  this  LEDATA  record  contain  8086  opcodes  for  each  of 
the  instruction  mnemonics  in  the  source  code.  The  gaps  (zero  values)  in  the  data  field 
correspond  to  address  values  that  the  assembler  cannot  resolve.  The  linker  will  fix  up  the 
address  values  in  the  gaps  by  computing  the  correct  values  and  adding  them  to  the  zero 
values  in  the  gaps.  The  FIXUPP  record  that  tells  the  linker  how  to  do  this  immediately 
follows  the  LEDATA  record  in  the  object  module: 

01  23456789ABCDEF 

0000  9C  21  00  84  01  06  01  02  80  04  06  01  02  CC  06  04  .! . 

0010  02  02  CC  OB  06  01  01  C4  10  00  01  01  15  00  C8  13  . 

0020  04  01  01  A3  .... 

•  Byte  OOH  contains  9CH,  indicating  this  is  a  FIXUPP  record. 

•  Bytes  01-02H  contain  0021H,  the  length  of  the  remainder  of  the  record. 

•  Bytes  03-07H  represent  the  first  of  the  six  fiocup  fields  in  this  record: 


The  information  in  this  fixup  field  will  allow  the  linker  to  resolve  the  address  refer¬ 
ence  in  the  statement 

jmp  NearLabel 
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-  Bytes  03-04H  (the  locat  field)  contain  8401H  (lOOOOlOOOOOOOOOlB).  (Recall  that 
this  field  does  not  conform  to  the  usual  Intel  byte  order.)  Bit  15  is  1,  signifying  that 
this  is  a  fiocup  field,  not  a  thread  field.  Bit  14  (the  M  bit)  is  0,  so  this  fixup  is  self¬ 
relative.  Bit  13  is  unused  and  should  be  set  to  0,  as  it  is  here.  Bits  12-10  (the  loc 
field)  contain  1  (OOIB),  so  the  LOCATION  to  be  fixed  up  is  a  l6-bit  offset.  Bits  9-0 
(the  data  record  offset)  contain  1  (OOOOOOOOOIB),  which  informs  the  linker  that  the 
LOCATION  to  be  fixed  up  is  at  offset  1  in  the  data  field  of  the  LEDATA  record  im¬ 
mediately  preceding  this  FIXUPP  record — in  other  words,  the  2  bytes  immedi¬ 
ately  following  the  first  opcode  0E9H. 

-  Byte  05H  (the  fix  dat  field)  contains  06H  (OOOOOllOB).  Bit  7  (the  F  bit)  is  0,  mean¬ 
ing  the  FRAME  for  this  fixup  is  explicitly  specified  in  this  fixup  field.  Bits  6-4 
(the  frame  field)  contain  0  (OOOB),  indicating  that  FRAME  method  0  specifies  the 
FRAME.  Bit  3  (the  T  bit)  is  0,  so  the  TARGET  for  this  fixup  is  also  explicitly  speci¬ 
fied.  Bits  2-0  (the  P  bit)  and  the  targt  field  contain  6  (HOB),  so  TARGET  method  6 
specifies  the  TARGET. 

-  Byte  06H  is  a  frame  datum  field,  because  the  FRAME  is  explicitly  specified  (the 
F  bit  of  the  fix  dat  field  =  0).  And,  because  method  0  is  specified,  the  frame 
datum  is  an  index  field  that  refers  to  a  previous  SEGDEF  record.  In  this  example, 
the  frame  datum  field  contains  1,  which  indicates  the  first  SEGDEF  record  in  the 
object  module:  the  _TEXT  segment. 

-  Similarly,  byte  07H  is  a  target  datum,  because  the  TARGET  is  also  explicitly  speci¬ 
fied  (the  T  bit  of  the  fix  dat  field  =  0).  The  fix  dat  field  also  indicates  that 
TARGET  method  6  is  used,  so  the  target  datum  is  an  index  field  that  refers  to  the 
external  reference  list  in  a  previous  EXTDEF  record.  The  value  of  this  index  is  2, 
so  the  TARGET  is  the  second  external  reference  declared  in  the  EXTDEF  record: 
NearLabel  in  this  object  module. 

•  Bytes  08-0CH  represent  the  second  fixup  field: 


01  234567  8  9ABCDEF 

0000  9C  21  .00  01  06  01  02^  80  04  06  01  02  g|^Q:6;04 
0010  02  62  'CC  OB  06  01.  Of  CC  m  00  01  01,  15~00  ;G8  13 


This  fixup  field  corresponds  to  the  statement 


jmp  short  NearLabel 

The  only  difference  between  this  statement  and  the  first  is  that  the  jump  uses  an  8-bit, 
rather  than  a  l6-bit,  offset.  Thus,  the  loc  field  (bits  12-10  of  byte  08H)  contains  0 
(OOOB)  to  indicate  that  the  LOCATION  to  be  fixed  up  is  a  low-order  byte. 

•  Bytes  OD-llH  represent  the  third  fixup  field  in  this  FIXUPP  record: 


This  fixup  field  corresponds  to  the  statement 


jmp  far  ptr  FarProc 
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In  this  case,  both  the  TARGET’S  frame  (the  segment  FAR_TEXT)  and  offset  (the  label 
FarProc^  are  known  to  the  assembler.  Both  the  segment  address  and  the  label  offset  are 
relocatable,  however,  so  in  the  FIXUPP  record  the  assembler  passes  the  responsibility 
for  resolving  the  addresses  to  the  linker. 

-  Bytes  OD-OEH  (the  local  field)  indicate  that  the  field  is  a  fixup  field  (bit  15  =  1) 
and  that  the  fixup  is  segment  relative  (bit  14 — the  M  bit  =  1).  The  loc  field  (bits 
12-10)  contains  3  (OllB),  so  the  LOCATION  being  fixed  up  is  a  32-bit  (FAR)  pointer 
(segment  and  offset).  The  data  record  offset  (bits  9-0)  is  6  (OOOOOOOllOB);  the 
LOCATION  is  the  4  bytes  following  the  first  far  jump  opcode  (EAH)  in  the  preced¬ 
ing  LEDATA  record. 

-  In  byte  OFH  (the  fix  dat  field),  the  F  bit  and  the  frame  field  are  0,  indicating  that 
method  0  (a  segment  index)  is  used  to  specify  the  FRAME.  The  T  bit  is  0  (meaning 
the  target  is  explicitly  defined  in  the  fixup  field);  therefore,  the  P  bit  and  targt 
fields  together  indicate  method  4  (a  segment  index)  to  specify  the  TARGET. 

-  Because  the  FRAME  is  specified  with  a  segment  index,  byte  lOH  (the  frame 
datum  field)  is  a  reference  to  the  second  SEGDEF  record  in  the  object  module, 
which  in  this  example  declared  the  FARJFEXT  segment.  Similarly,  byte  IIH  (the 
target  datum  field)  references  the  FAR_^TEXT  segment.  In  this  case,  the  FRAME 
is  the  same  as  the  TARGET  segment;  had  FAR_TEXT  been  one  of  a  group  of  seg¬ 
ments,  the  FRAME  could  have  referred  to  the  group  instead. 

•  The  fourth  assembler  statement  is  different  from  the  third  because  it  references  a 

segment  not  known  to  the  assembler: 


jmp  FarLabel 

Bytes  12-16H  contain  the  corresponding  fixup  field: 


The  significant  difference  between  this  and  the  preceding  fixup  field  is  that  the 
P  bit  and  targt  field  of  the  fix  dat  byte  (byte  14H)  specify  TARGET  method  6.  In  this 
fixup  field,  the  target  datum  (byte  16H)  refers  to  the  first  EXTDEF  record  in  the 
object  module,  which  declares  FarLabel  as  an  external  reference. 

•  The  fifth  fixup  field  (bytes  17-lDH)  is 


01  23456789ABCDEF 

■0  .30  2t>  0P-:84  04  06<  01  02  80X04  06^  01  02 ‘%iqj6:  04 

10  00  01  01  15  00  .QBynr..i, 


This  fiocup  field  contains  information  that  enables  the  linker  to  calculate  the  value  of 
the  relocatable  offset  LocalLabeU 


mov  bx, offset  LocalLabel 
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-  Bytes  17-18H  (the  locat  field)  contain  C410H  (IIOOOIOOOOOIOOOOB).  Bit  15  is  1, 
denoting  a  fiocup  field.  The  M  bit  (bit  14)  is  1,  indicating  that  this  fixup  is  segment 
relative.  The  loc  field  (bits  12-10)  contains  1  (OOIB),  so  the  LOCATION  is  a  l6-bit 
offset.  The  data  record  offset  (bits  9-0)  is  lOH  (OOOOOIOOOOB),  a  reference  to  the 
2  bytes  in  the  LEDATA  record  following  the  opcode  OBBH. 

-  Byte  19H  (the  fix  dat  byte)  contains  OOH.  The  F  bit,  frame  field,  T  bit,  P  bit,  and 
targt  field  are  all  0,  so  FRAME  method  0  and  TARGET  method  0  are  explicitly 
specified  in  this  fixup  field. 

-  Because  FRAME  method  0  is  used,  byte  lAH  (the  frame  datum  field)  is  an  index 
field.  It  contains  OlH,  a  reference  to  the  first  SEGDEF  record  in  the  object  module, 
which  declares  the  segment  ^TEXT. 

Similarly,  byte  IBH  (the  target  datum  field)  references  the  ^TEXT  segment. 

-  Because  TARGET  method  0  is  specified,  an  offset,  in  addition  to  a  segment,  is 
required  to  define  the  TARGET.  This  offset  appears  in  the  target  displacement 
field  in  bytes  IC-IDH.  The  value  of  this  offset  is  0015H,  corresponding  to  the  offset 
of  the  TARGET  CLocalLabeO  in  its  segment  C_TEXT), 

•  The  sixth  and  final  fiocup  field  in  this  FIXUPP  record  (bytes  1E-22H)  is 


01  23456789ABCDEF 


This  corresponds  to  the  segment  of  the  relocatable  address  LocalLabeh 


mov  ax,seg  LocalLabel 

-  Bytes  lE-lFH  (the  locat  field)  contain  C813H  (IIOOIOOOOOOIOOIIB).  Bit  15  is  1,  so 
this  is  a  fiocup  field.  The  M  bit  (bit  14)  is  1,  so  the  fixup  is  segment  relative.  The  loc 
field  (bits  12-10)  contains  2  (OlOB),  so  the  LOCATION  is  a  l6-bit  segment  value. 
The  data  record  offset  (bits  9-0)  indicates  the  2  bytes  in  the  LEDATA  record 
following  the  opcode  0B8H. 

-  Byte  20H  (the  fix  dat  byte)  contains  04H,  so  FRAME  method  0  and  TARGET 
method  4  are  explicitly  specified  in  this  fiocup  field. 

-  Byte  21H  (the  frame  datum  field)  contains  OlH.  Because  FRAME  method  0  is 
specified,  the  frame  datum  is  an  index  value  that  refers  to  the  first  SEGDEF  record 
in  the  object  module  (corresponding  to  the  _  TEXT  segment). 

-  Byte  22H  (the  target  datum  field)  contains  OlH.  Because  TARGET  method  4  is 
specified,  the  target  datum  also  references  the  ^TEXT  segment. 

•  Finally,  byte  23H  contains  this  FIXUPP  record’s  checksum,  0A3H. 

The  next  two  FIXUPP  records  show  how  thread  fields  are  used.  The  first  of  the  two 
contains  six  thread  fields  that  can  be  referenced  by  both  thread  and  fiocup  fields  in  sub¬ 
sequent  FIXUPP  records  in  the  same  object  module: 

01  23456789ABCDEF 

0000  9C  OD  00  00  03  01  02  02  01  03  04  40  01  45  01  CO  . @ - 
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Bytes  03-04H,  05-06H,  07-08H,  09-0AH,  OB-OCH,  and  OD-OEH  represent  the  six 
thread  fields  in  this  FIXUPP  record.  The  high-order  bit  of  the  first  byte  of  each  of  these 
fields  is  0,  indicating  that  they  are,  indeed,  thread  fields  and  not  fixup  fields. 

•  Byte  03H,  which  contains  OOH,  is  the  thread  data  byte  of  the  first  thread  field.  Bit  7 
of  this  byte  is  0,  indicating  this  is  a  thread  field.  Bit  6  (the  D  bit)  is  0,  so  this  field 
specifies  a  TARGET.  Bit  5  is  0,  as  it  must  always  be.  Bits  4  through  2  (the  method  field) 
contain  0  (OOOB),  which  specifies  TARGET  method  0.  Finally,  bits  1  and  0  contain  0 
(OOB),  the  thread  number  that  identifies  this  thread  field. 

Byte  04H  represents  a  segment  index  field,  because  method  0  of  specifying  a 
TARGET  references  a  segment.  The  value  of  the  index,  3,  is  a  reference  to  the  third 
SEGDEF  record  defined  in  the  object  module. 

•  Bytes  05-06H,  07-08H,  and  09-0AH  contain  similar  thread  fields.  In  each,  the 
method  field  specifies  TARGET  method  0.  The  three  thread  fields  also  have  thread 
numbers  of  1, 2,  and  3.  Because  TARGET  method  0  is  specified  for  each  thread  field, 
bytes  06H,  OSH,  and  OAH  represent  s^ment  index  fields,  which  reference  the 
second,  first,  and  fourth  SEGDEF  records,  respectively. 

•  Byte  OBH  (the  thread  data  byte  of  the  fifth  thread  field  in  this  FIXUPP  record)  con¬ 
tains  40H  (OlOOOOOOB).  The  D  bit  (bit  6)  is  1,  so  this  thread  field  specifies  a  FRAME. 
The  method  field  (bits  4  through  2)  contains  0  (OOOB),  which  specifies  FRAME 
method  0.  Byte  OCH  (which  contains  OlH)  is  therefore  interpreted  as  a  segment  index 
reference  to  the  first  SEGDEF  record  in  the  object  module. 

•  Byte  ODH  is  the  thread  data  byte  of  the  sixth  thread  field.  It  contains  45H 
(OIOOOIOIB).  Bit  6  is  1,  which  indicates  that  this  thread  specifies  a  FRAME.  The 
method  field  (bits  4  through  2)  contains  1  (OOIB),  which  specifies  FRAME  method  1. 
Byte  OEH  (which  contains  OlH)  is  therefore  interpreted  as  a  group  index  to  the  first 
preceding  GRPDEF  record. 

The  thread  number  fields  of  the  fifth  and  sixth  thread  fields  contain  0  and  1,  respec¬ 
tively,  but  these  thread  numbers  do  not  conflict  with  the  ones  used  in  the  first  and 
second  thread  fields,  because  the  latter  represent  TARGET  references,  not  FRAME 
references. 

The  next  FIXUPP  example  appears  after  the  preceding  record,  in  the  same  object  module. 
This  FIXUPP  record  contains  a  fixup  field  in  bytes  03-05H  that  refers  to  a  thread  in  the 
previous  FIXUPP  record: 

01  23456789ABCDEF 

0000  9C  04  00  C4  09  9D  F6  _ ... 

•  Bytes  03-04H  represent  the  l6-bit  locat  field,  which  contains  C409H 
(IIOOOIOOOOOOIOOIB).  Bit  15  of  the  locat  field  is  1,  indicating  a  fixup  field.  The  M  bit 
(bit  14)  is  1,  so  this  fixup  is  relative  to  a  particular  segment,  which  is  specified  later  in 
the  fixup  field.  Bit  13  is  0,  as  it  should  be.  Bits  12-10  (the  loc  field)  contain  1  (OOIB), 
so  the  LOCATION  to  be  fixed  up  is  a  l6-bit  offset.  Bits  9-0  (the  data  record  offset 
field)  contain  9  (OOOOOOIOOIB),  so  the  LOCATION  to  be  fixed  up  is  represented  at  an 
offset  of  9  bytes  into  the  data  field  of  the  preceding  LEDATA  or  LIDATA  record. 
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•  Byte  05H  (the  fix  dat  byte)  contains  9DH  (lOOlllOlB).  The  F  bit  (bit  7)  is  1,  so  this 

fixup  field  references  a  thread  field  that,  in  turn,  defines  the  method  of  specifying 
the  FRAME  for  the  fixup.  Bits  6-4  (the  frame  field)  contain  1  (OOIB),  the  number  of 
the  thread  that  contains  the  FRAME  method.  This  thread  contains  a  method  number 
of  1,  which  references  the  first  GRPDEF  record  in  the  object  module,  thus  specifying 
the  FRAME. 

The  T  bit  (bit  3  in  the  fix  dat  byte)  is  1,  so  the  TARGET  method  is  also  defined  in  a 
preceding  thread  field.  The  targt  field  (bits  1  and  0  in  the  fix  dat  byte)  contains  1 
(OIB),  so  the  TARGET  thread  field  whose  thread  number  is  1  specifies  the  TARGET. 
The  P  bit  (bit  3  in  the  fix  dat  byte)  contains  1,  which  is  combined  with  the  low-order 
bits  of  the  method  field  in  the  thread  field  that  describes  the  target  to  obtain  TARGET 
method  number  4  (lOOB).  The  TARGET  thread  references  the  second  SEGDEF  record 
to  specify  the  TARGET. 

The  last  FIXUPP  example  illustrates  that  the  linker  performs  a  fixup  by  adding  the  calcu¬ 
lated  address  value  to  the  value  in  the  LOCATION  being  fixed  up.  This  function  of  the 
linker  can  be  exploited  to  use  fixups  to  modify  opcodes  or  program  data,  as  well  as  to 
resolve  address  references. 

Consider  how  the  following  assembler  instruction  might  be  fixed  up: 

lea  bx,alpha+10h  ;  alpha  is  an  external  symbol 

Typically,  this  instruction  is  translated  into  an  LEDATA  record  with  zero  in  the  LOCATION 
(bytes  08-09H)  to  be  fixed  up: 

01  23456789ABCDEF 

0000  AO  08  00  01  00  00  8D  IE  00  00  AC  . 

The  corresponding  FIXUPP  record  contains  a  target  displacement  of  lOH  bytes  (bytes 
08-09H): 

01  23456789ABCDEF 

0000  9C  08  00  C4  02  02  01  01  10  00  82  . 

This  FIXUPP  record  specifies  TARGET  method  2,  which  is  indicated  by  the  targt  field 
(bits  2-0)  of  the  fixdat  field  (byte  05H).  In  this  case,  the  linker  adds  the  target  displace¬ 
ment  to  the  address  it  has  determined  for  the  TARGET  ialphd)  and  then  completes  the 
fixup  by  adding  this  calculated  address  value  to  the  zero  value  in  the  LOCATION. 

The  same  result  can  be  achieved  by  storing  the  displacement  (lOH)  directly  in  the 
LOCATION  in  the  LEDATA  record: 

01  23456789ABCDEF 

0000  AO  08  00  01  00  00  8D  IE  10  00  9C  . 

Then,  the  target  displacement  can  be  omitted  from  the  FIXUPP  record: 

01  23456789ABCDEF 

0000  9C  06  00  C4  02  06  01  01  90  . 
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This  FIXUPP  record  specifies  TARGET  method  6,  which  does  not  use  a  target  displace¬ 
ment.  The  linker  performs  this  fixup  by  adding  the  address  of  alpha  to  the  value  in  the 
LOCATION,  so  the  result  is  identical  to  the  preceding  one. 

The  difference  between  the  two  techniques  is  that  in  the  latter  the  linker  does  not  perform 
error  checking  when  it  adds  the  calculated  fixup  value  to  the  value  in  the  LOCATION.  If 
this  second  technique  is  used,  the  linker  will  not  flag  arithmetic  overflow  or  underflow 
errors  when  it  adds  the  displacement  to  the  TARGET  address.  The  first  technique,  then, 
traps  all  errors;  the  second  can  be  used  when  overflow  or  underflow  is  irrelevant  and  an 
error  message  would  be  undesirable. 
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OAOH  LEDATA  Logical  Enumerated  Data  Record 

The  LEDATA  record  contains  contiguous  binary  data — executable  code  or  program 
data — that  is  eventually  copied  into  the  program’s  executable  binary  image. 

The  binary  data  in  an  LEDATA  record  can  be  modified  by  the  linker  if  the  record  is  fol¬ 
lowed  by  a  FIXUPP  record. 

Record  format 


1 

- - 

- 1 - 

- - 

AOH 

length 

segment  index 

enumerated 
data  offset 

data 

chk 

sum 

1 

- - 

1 

- ✓/X - 7 

can  be  X' 
repeated 


Segment  index 

The  segment  index  is  a  variable-length  index  field.  The  index  number  in  this  field  refers 
to  a  previous  SEGDEF  record  in  the  object  module.  A  value  of  1  indicates  the  first  SEGDEF 
record,  a  value  of  2  the  second,  and  so  on.  That  SEGDEF  record,  in  turn,  indicates  the 
segment  into  which  the  data  in  this  LEDATA  record  is  to  be  placed. 

Enumerated  data  offset 

The  enumerated  data  offset  is  a  2-byte  offset  into  the  segment  referenced  by  the  segment 
index,  relative  to  the  base  of  the  segment.  Taken  together,  the  segment  index  and  the 
enumerated  data  offset  fields  indicate  the  location  where  the  enumerated  data  will  be 
placed  in  the  run-time  memory  map. 

Data 

The  data  field  contains  the  actual  data,  which  can  be  either  executable  8086  instructions 
or  program  data.  The  maximum  size  of  the  data  field  is  1024  bytes. 

Location  in  object  module 

Any  LEDATA  records  in  an  object  module  must  be  preceded  by  the  SEGDEF  records  to 
which  they  refer.  Also,  if  an  LEDATA  record  requires  a  fixup,  a  FIXUPP  record  must  imme¬ 
diately  follow  the  LEDATA  record. 

Example 

The  following  LEDATA  record  contains  a  simple  text  string: 

01  23456789ABCDEF 


0000  AO  13  00  02  00  00  48  65  6C  6C  6F  2C  20  77  6F  72  . Hello,  wor 

0010  6C  64  OD  OA  24  A8  ld..$. 


•  Byte  OOH  contains  OAOH,  which  identifies  this  as  an  LEDATA  record. 

•  Bytes  01-02H  contain  0013H,  the  length  of  the  remainder  of  the  record. 
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•  Byte  03H  (the  segment  index  field)  contains  02H,  a  reference  to  the  second  SEGDEF 
record  in  the  object  module. 

•  Bytes  04-05H  (the  enumerated  data  offset  field)  contain  OOOOH.  This  is  the  offset, 
from  the  base  of  the  segment  indicated  by  the  segment  index  field,  at  which  the  data 
in  the  data  field  will  be  placed  when  the  program  is  linked.  Of  course,  this  offset  is 
subject  to  relocation  by  the  linker  because  the  segment  declared  in  the  specified 
SEGDEF  record  may  be  relocatable  and  may  be  combined  with  other  segments 
declared  in  other  object  modules. 

•  Bytes  06-14H  (the  data  field)  contain  the  actual  data. 

•  Byte  15H  contains  the  checksum,  0A8H. 
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0A2H  LIDATA  Logical  Iterated  Data  Record 

Like  the  LEDATA  record,  the  LIDATA  record  contains  binary  data — executable  code  or 
program  data.  The  data  in  an  LIDATA  record,  however,  is  specified  as  a  repeating  pattern 
(iterated),  rather  than  by  explicit  enumeration. 

The  data  in  an  LIDATA  record  may  be  modified  by  the  linker  if  the  LIDATA  record  is 
followed  by  a  FEXUPP  record. 

Record  format 


1 

- - 

1 

- - 

A2H 

length 
_ « 

segment  index 

- - 

iterated 
data  offset 

iterated  data  block 

^ 

chk 

sum 

^can  bex 
repeated 


Segment  index 

The  segment  index  is  a  variable-length  index  field.  The  index  number  in  this  field  refers 
to  a  previous  SEGDEF  record  in  the  object  module.  A  value  of  1  indicates  the  first  SEGDEF 
record,  2  indicates  the  second,  and  so  on.  That  SEGDEF  record,  in  turn,  indicates  the 
segment  into  which  the  data  in  this  LIDATA  record  is  to  be  placed  when  the  program  is 
executed. 

Iterated  data  offset 

The  iterated  data  offset  is  a  2-byte  offset  into  the  segment  referenced  by  the  segment 
index,  relative  to  the  base  of  the  segment.  Taken  together,  the  segment  index  and  the 
iterated  data  offset  fields  indicate  the  location  where  the  iterated  data  will  be  placed  in 
the  run-time  memory  map. 

Iterated  data  block 

The  iterated  data  block  is  a  variable-length  field  containing  the  actual  data — executable 
code  and  program  data.  Iterated  data  blocks  can  be  nested,  so  one  iterated  data  block 
can  contain  one  or  more  other  iterated  data  blocks,  Microsoft  LINK  restricts  the  maximum 
size  of  an  iterated  data  block  to  512  bytes. 

The  format  of  the  iterated  data  block  is 


- 1 - 

- - 

repeat 

count 

block 

count 

_ 1 _ 

content 

- - 

•  Repeat  count  is  a  2-byte  field  indicating  the  number  of  times  the  content  field  is  to 
be  repeated. 

•  Block  count  is  a  2-byte  field  indicating  the  number  of  iterated  data  blocks  in  the 
content  field.  If  the  block  count  is  0,  the  content  field  contains  data  only. 
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•  Content  is  a  variable-length  field  that  can  contain  either  nested  iterated  data  blocks 
(if  the  block  count  is  nonzero)  or  data  (if  the  block  count  is  0).  If  the  content  field 
contains  data,  the  field  contains  a  1-byte  count  of  the  number  of  data  bytes  in  the  field, 
followed  by  the  actual  data. 

Location  in  object  module 

Any  LIDATA  records  in  an  object  module  must  be  preceded  by  the  SEGDEF  records  to 
which  they  refer.  Also,  if  an  LIDATA  record  requires  a  fixup,  a  FIXUPP  record  must  imme¬ 
diately  follow  the  LIDATA  record. 

Example 

This  sample  LIDATA  record  corresponds  to  the  following  assembler  statement,  which 
declares  a  10-element  array  containing  the  strings  ALPHA  and  BETA. 

db  10  dupC ALPHA',  'BETA') 

The  LIDATA  record  is 

01  23456789ABCDEF 

0000  A2  IB  00  01  00  00  OA  00  02  00  01  00  00  00  05  41  . A 

0010  4C  50  48  41  01  00  00  00  04  42  45  54  41  A9  LPHA . BETA. 

•  Byte  OOH  contains  0A2H,  identifying  this  as  an  LIDATA  record. 

•  Bytes  01-02H  contain  IBH,  the  length  of  the  remainder  of  the  record. 

•  Byte  03H  (the  segment  indeoc)  contains  OlH,  a  reference  to  the  first  SEGDEF  record  in 
this  object  module,  indicating  that  the  data  declared  in  this  LIDATA  record  is  to  be 
placed  into  the  segment  described  by  the  first  SEGDEF  record. 

•  Bytes  04-05H  (the  iterated  data  offset)  contain  OOOOH,  so  the  data  in  this  LIDATA 
record  is  to  be  located  at  offset  OOOOH  in  the  segment  designated  by  the  segment 
index. 

•  Bytes  06-ICH  represent  an  iterated  data  block: 

-  Bytes  06-07H  contain  the  repeat  count,  OOOAH,  which  indicates  that  the  content 
field  of  this  iterated  data  block  is  to  be  repeated  10  times. 

-  Bytes  08-09H  (the  block  count  for  this  iterated  data  block)  contain  0002H,  which 
indicates  that  the  content  field  of  this  iterated  data  block  (bytes  OA-ICH)  con¬ 
tains  two  nested  iterated  data  block  fields  (bytes  0A-13H  and  bytes  14-lCH). 

-  Bytes  OA-OBH  contain  OOOIH,  the  repeat  count  for  the  first  nested  iterated  data 
block.  Bytes  OC-ODH  contain  OOOOH,  indicating  that  the  content  field  of  this 
nested  iterated  data  block  contains  data,  rather  than  more  nested  iterated  data 
blocks.  The  content  field  (bytes  0E-13H)  contains  the  data:  Byte  OEH  contains 
05H,  the  number  of  subsequent  data  bytes,  and  bytes  0F-13H  contain  the  actual 
data  (the  string  ALPHA). 

-  Bytes  14-lCH  represent  the  second  nested  iterated  data  block,  which  has  a  format 
similar  to  that  of  the  block  in  bytes  0A-13H.  This  second  nested  iterated  data 
block  represents  the  4-byte  string  BETA. 

•  Byte  IDH  is  the  checksum,  0A9H. 
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OBOH  COMDEF  Communal  Names  Definition  Record 

The  COMDEF  record  is  a  Microsoft  extension  to  the  basic  set  of  8086  object  record  types 
defined  by  Intel  that  declares  a  list  of  one  or  more  communal  variables.  The  COMDEF 
record  is  recognized  by  versions  3  50  and  later  of  LINK.  Microsoft  encourages  the  use 
of  the  COMDEF  record  for  declaration  of  communal  variables. 

Record  format 


data 

segment 

type 

- - 

BOH 

type 

index 

communal 

length 

- 

chk 

sum 

^can  be- 
repeated 


Communal  name 

The  communal  name  field  is  a  variable-length  field  that  contains  the  name  of  a  communal 
variable.  The  first  byte  of  this  field  indicates  the  length  of  the  name  contained  in  the  re¬ 
mainder  of  the  field. 

Type  index 

The  type  index  field  is  an  index  field  that  references  a  previous  T YPDEF  record  in  the 
object  module.  A  value  of  1  indicates  the  first  TYPDEF  record  in  the  module,  a  value  of  2 
indicates  the  second,  and  so  on.  The  type  index  value  can  be  0  if  no  data  type  is  associated 
with  the  public  name. 

Data  segment  type 

The  data  segment  type  field  is  a  single  byte  that  indicates  whether  the  communal  variable 
is  FAR  or  NEAR.  There  are  only  two  possible  values  for  data  segment  type: 

6lH  FAR  variable 

62H  NEAR  variable 

Communal  length 

The  communal  length  is  a  variable-length  field  that  indicates  the  amount  of  memory  to  be 
allocated  for  the  communal  variable.  The  contents  of  this  field  depend  on  the  value  in  the 
data  segment  type  field.  If  the  data  segment  type  is  NEAR  (62H),  the  communal  length 
field  contains  the  size  (in  bytes)  of  the  communal  variable: 

- - 

variable  size 
- - 
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If  the  data  segment  type  is  FAR  (6lH),  the  communal  length  field  is  formatted  las  follows: 


- - 

- - 

number  of 
elements 

element  size 

- — - 

- - 

A  FAR  communal  variable  is  viewed  as  an  array  of  elements  of  a  specified  size.  Thus,  the 
number  of  elements  field  is  a  variable-length  field  representing  the  number  of  elements  in 
the  array,  and  the  element  size  field  is  a  variable-length  field  that  indicates  the  size  (in 
bytes)  of  each  element.  The  amount  of  memory  required  for  a  FAR  communal  variable  is 
thus  the  product  of  the  number  of  elements  and  the  element  size. 

The  format  of  the  variable  size,  number  of  elements,  and  element  size  fields  depends  upon 
the  magnitude  of  the  values  they  contain: 

•  If  the  value  is  less  than  128  (80H),  the  field  is  formatted  as  a  1-byte  field  containing  the 
actual  value: 


value 


•  If  the  value  is  128  (80H)  or  greater,  the  field  is  formatted  with  an  extra  initial  byte  that 
indicates  whether  the  value  is  represented  in  the  subsequent  2,  3,  or  4  bytes: 


Groups  of  communal  name,  type  index,  data  segment  type,  and  communal  length  fields 
can  be  repeated  so  that  more  than  one  communal  variable  can  be  declared  in  the  same 
COMDEF  record. 

Location  in  object  module 

Any  object  module  that  contains  COMDEF  records  must  also  contain  one  COMENT  record 
with  the  comment  class  OAIH,  indicating  that  Microsoft  extensions  to  the  Intel  object 
record  specification  are  included  in  the  object  module.  This  COMENT  record  must  appear 
before  any  COMDEF  records  in  the  object  module. 
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Example 

The  following  COMDEF  record  was  generated  by  the  Microsoft  C  Compiler  version  4.0  for 
these  public  variable  declarations: 

int  foo;  /*  2-byte  integer  */ 

char  foo2 [32768];  /*  32768-byte  array  */ 

char  far  foo3 [1 0] [2] [20] ;  /*  400-byte  array  */ 

The  COMDEF  record  is 

01  2345678,  9ABCDEF 

0000  BO  20  00  04  5F  66  6F  6F  00  62  02  05  5F  66  6F  6F  .  _ foo.b _ foo 

0010  32  00  62  81  00  80  05  5F  66  6F  6F  33  00  61  81  90  2.b _ foo3.a.. 

0020  01  01  99 

•  Byte  OOH  contains  OBOH,  indicating  that  this  is  a  COMDEF  record. 

•  Bytes  01-02H  contain  0020H,  the  length  of  the  remainder  of  the  record. 

•  Bytes  03--0AH,  0B-15H,  and  16-21H  represent  three  declarations  for  the  communal 
variables  foo,  foo2,  and  fooi.  The  C  compiler  prepends  an  underscore  to  each  of  the 
names  declared  in  the  source  code,  so  the  symbols  represented  in  this  COMDEF 
record  are  —foo,  —foo2,  and  —foo3> 

-  Byte  03H  contains  04H,  the  length  of  the  first  communal  name  in  this  record. 
Bytes  04-07H  contain  the  name  itself  i—fo6).  Byte  OSH  (the  type  index  field)  con¬ 
tains  OOH,  as  required.  Byte  09H  (the  data  segment  type  field)  contains  62H,  indi¬ 
cating  this  is  a  NEAR  variable.  Byte  OAH  (the  communal  length  field)  contains 
02H,  the  size  of  the  variable  in  bytes. 

-  Byte  OBH  contains  05H,  the  length  of  the  second  communal  name.  Bytes  OC-lOH 
contain  the  name,  —foo2.  Byte  IIH  is  the  type  index  field,  which  again  contains 
OOH  as  required.  Byte  12H  (the  data  segment  type  field)  contains  62H,  indicating 
that  —foo2  is  a  NEAR  variable. 

Bytes  13-15H  (the  communal  length  field)  contain  the  size  in  bytes  of  the  variable. 
The  first  byte  of  the  communal  length  field  (byte  13H)  is  81H,  indicating  that  the 
size  is  represented  in  the  subsequent  2  bytes  of  data — bytes  14-15H,  which  con¬ 
tain  the  value  8000H. 

-  Bytes  16--1BH  represent  the  communal  name  field  for  —foo3,  the  third  communal 
variable  declared  in  this  record.  Byte  ICH  (the  type  index  field)  again  contains 
OOH  as  required.  Byte  IDH  (the  data  segment  type  field)  contains  6lH,  indicating 
this  is  a  FAR  variable.  This  means  the  communal  length  field  is  formatted  as  a 
number  of  elements  field  (bytes  1E~20H,  which  contain  the  value  0190H)  and  an 
element  size  field  (byte  21H,  which  contains  OlH).  The  total  size  of  this  communal 
variable  is  thus  190H  times  1,  or  400  bytes. 

•  Byte  22H  contains  the  checksum,  99H. 


Richard  Wilton 


700  The  MS-DOS  Encyclopedia 


Article  20:  The  Microsoft  Object  Linker 


Article  20 

The  Microsoft  Object  Linker 


MS-DOS  object  modules  can  be  processed  in  two  ways:  They  can  be  grouped  together  in 
object  libraries,  or  they  can  be  linked  into  executable  files.  All  Microsoft  language  transla¬ 
tors  are  distributed  with  two  utility  programs  that  process  object  modules:  The  Microsoft 
Library  Manager  (LIB)  creates  and  modifies  object  libraries;  the  Microsoft  Object  Linker 
(LINK)  processes  the  individual  object  records  within  object  modules  to  create  executable 
files. 

The  following  discussion  focuses  on  LINK  because  of  its  crucial  role  in  creating  an  execut¬ 
able  file.  Before  delving  into  the  complexities  of  LINK,  however,  it  is  worthwhile  reviewing 
how  object  modules  are  managed. 


Object  Files,  Object  libraries,  and  LIB 

Compilers  and  assemblers  translate  source-code  modules  into  object  modules  (Figure 
20-1).  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  Tools: 
Object  Modules.  An  object  module  consists  of  a  sequence  of  object  records  that  describe 
the  form  and  content  of  part  of  an  executable  program.  An  MS-DOS  object  module  always 
starts  with  a  THEADR  record;  subsequent  object  records  in  the  module  follow  the 
sequence  discussed  in  the  Object  Modules  article. 

Object  modules  can  be  stored  in  either  of  two  types  of  MS-DOS  files:  object  files  and  object 
libraries.  By  convention,  object  files  have  the  filename  extension  .OBJ  and  object  libraries 
have  the  extension  .LIB.  Although  both  object  files  and  object  libraries  contain  one  or 


(Program  runs) 

Figure  20-1.  Object  modules,  object  libraries,  LIB,  and  LINK. 
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more  object  modules,  the  files  and  the  libraries  have  different  internal  organization. 
Furthermore,  LINK  processes  object  files  and  libraries  differently. 

The  structures  of  object  files  and  libraries  are  compared  in  Figure  20-2.  An  object  file  is  a 
simple  concatenation  of  object  modules  in  any  arbitrary  order.  (Microsoft  discourages  the 
use  of  object  files  that  contain  more  than  one  object  module;  Microsoft  language  translators 
never  generate  more  than  one  object  module  in  an  object  file.)  In  contrast,  a  library  con¬ 
tains  a  hashed  dictionary  of  all  the  public  symbols  declared  in  each  of  the  object  modules, 
in  addition  to  the  object  modules  themselves.  Each  symbol  in  the  dictionary  is  associated 
with  a  reference  to  the  object  module  in  which  the  symbol  was  declared. 

LINK  processes  object  files  differently  than  it  does  libraries.  When  LINK  builds  an  execut¬ 
able  file,  it  incorporates  all  the  object  modules  in  all  the  object  files  it  processes.  In  con¬ 
trast,  when  LINK  processes  libraries,  it  uses  the  hashed  symbol  dictionary  in  each  library 
to  extract  object  modules  selectively — it  uses  an  object  module  from  a  library  only  when 
the  object  module  contains  a  symbol  that  is  referenced  within  some  other  object  module. 
This  distinction  between  object  files  and  libraries  is  important  in  understanding  what 
LINK  does. 


(a) 


Object  module 


Object  module 


Object  module 


Library  header 


Object  module 


Object  module 


Object  module 


Symbol  dictionary 


Figure  20-2.  Structures  of  an  object file  and  an  object  library,  (a)  An  object file  contains  one  or  more  object 
modules.  (Microsoft  discourages  using  more  than  one  object  module  per  object file.)  (b)  An  object  library  con¬ 
tains  one  or  more  object  modules  plus  a  hashed  symbol  dictionary  indicating  the  object  modules  in  which 
each  public  symbol  is  defined. 
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What  LINK  Does 

The  function  of  LINK  is  to  translate  object  modules  into  an  executable  program.  LINK’S 
input  consists  of  one  or  more  object  files  (.OBJ  files)  and,  optionally,  one  or  more  libraries 
(.LIB  files).  LINK’S  output  is  an  executable  file  (.EXE  file)  containing  binary  data  that  can 
be  loaded  directly  from  the  file  into  memory  and  executed.  LINK  can  also  generate  a  sym¬ 
bolic  address  map  listing  (.MAP  file) — a  text  file  that  describes  the  organization  of  the 
.EXE  file  and  the  correspondence  of  symbols  declared  in  the  object  modules  to  addresses 
in  the  executable  file. 

Building  an  executable  file 

LINK  builds  two  types  of  information  into  a  .EXE  file.  First,  it  extracts  executable  code  and 
data  from  the  LEDATA  and  LIDATA  records  in  object  modules,  arranges  them  in  a  specified 
order  according  to  its  rules  for  segment  combination  and  relocation,  and  copies  the  result 
into  the  .EXE  file.  Second,  LINK  builds  a  header  for  the  .EXE  file.  The  header  describes  the 
size  of  the  executable  program  and  also  contains  a  table  of  load-time  segment  relocations 
and  initial  values  for  certain  CPU  registers.  See  Pass  2  below. 

Relocation  and  linking 

In  building  an  executable  image  from  object  modules,  LINK  performs  two  essential  tasks: 
relocation  and  linking.  As  it  combines  and  rearranges  the  executable  code  and  data  it  ex¬ 
tracts  from  the  object  modules  it  processes,  LINK  frequently  adjusts,  or  relocates,  address 
references  to  account  for  the  rearrangements  (Figure  20-3).  LINK  links  object  modules  by 
resolving  address  references  among  them.  It  does  this  by  matching  the  symbols  declared 
in  EXTDEF  and  PUBDEF  object  records  (Figure  20-4).  LINK  uses  FDCUPP  records  to  deter¬ 
mine  exactly  how  to  compute  both  address  relocations  and  linked  address  references. 


Object  Module  Order 

LINK  processes  input  files  from  three  sources:  object  files  and  libraries  specified  explicitly 
by  the  user  (in  the  command  line,  in  response  to  LINK’S  prompts,  or  in  a  response  file) 
and  object  libraries  named  in  object  module  COMENT  records. 


Code  segment  (64H  bytes) 
Label  1  at  offset  lOH 

Module  1 


Code  segment  (50H  bytes) 
Label2  at  offset  lOH 


Module2 


Code  segment  (B4H  bytes) 

Label  1  at  offset  lOH 
Label2  at  offset  74H 


Combined  code  segment 


Figure  20-3-  A  simple  relocation.  Both  object  modules  contain  code  that  LINK  combines  into  one  logical 
segment.  In  this  example,  LINK  appends  the  50H  bytes  of  code  in  Module2  to  the  64H  bytes  of  code  in  Modulel. 
LINK  relocates  all  references  to  addresses  in  the  code  segment  so  that  they  apply  to  the  combined  segment. 
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Code  segment 
PUBDEFLabel2 

Label2: 

Module2 

Figure  20-4.  Resolving  an  external  reference.  LINK  resolves  the  external  reference  in  Modulel  (declared  in 
an  EXTDEF  record)  with  the  address  of  Label2  in  Module2  (declared  in  a  PUBDEF  record). 

LINK  always  uses  all  the  object  modules  in  the  object  files  it  processes.  In  contrast,  it 
extracts  individual  object  modules  from  libraries — only  those  object  modules  needed  to 
resolve  references  to  public  symbols  are  used.  This  difference  is  implicit  in  the  order  in 
which  LINK  reads  its  input  files: 

1.  Object  files  specified  in  the  command  line  or  in  response  to  the  Object  Modules 
prompt 

2.  Libraries  specified  in  the  command  line  or  in  response  to  the  Libraries  prompt 

3.  Libraries  specified  in  COMENT  records 

The  order  in  which  LINK  processes  object  modules  influences  the  resulting  executable 
file  in  three  ways.  First,  the  order  in  which  segments  appear  in  LINK’S  input  files  is 
reflected  in  the  segment  structure  of  the  executable  file.  Second,  the  order  in  which  LINK 
resolves  external  references  to  public  symbols  depends  on  the  order  in  which  it  finds  the 
public  symbols  in  its  input  files.  Finally,  LINK  derives  the  default  name  of  the  executable 
file  from  the  name  of  the  first  input  object  file. 

Segment  order  in  the  executable  file 

In  general,  LINK  builds  named  segments  into  the  executable  file  in  the  order  in  which  it 
first  encounters  the  SEGDEF  records  that  declare  the  segments.  (The  /DOSSEG  switch  also 
affects  segment  order.  See  Using  the  /DOSSEG  Switch  below.)  This  means  that  the  order  in 
which  segments  appear  in  the  executable  file  can  be  controlled  by  linking  object  modules 
in  a  specific  order.  In  assembly-language  programs,  it  is  best  to  declare  all  the  segments 
used  in  the  program  in  the  first  object  module  to  be  linked  so  that  the  segment  order  in 
the  executable  file  is  under  complete  control. 

Order  in  which  references  are  resolved 

LINK  resolves  external  references  in  the  order  in  which  it  encounters  the  corresponding 
public  declarations.  This  fact  is  important  because  it  determines  the  order  in  which  LINK 
extracts  object  modules  from  libraries.  When  a  public  symbol  required  to  resolve  an  exter¬ 
nal  reference  is  declared  more  than  once  among  the  object  modules  in  the  input  libraries, 
LINK  uses  the  first  object  module  that  contains  the  public  symbol.  This  means  that  the 
actual  executable  code  or  data  associated  with  a  particular  external  reference  can  be 
varied  by  changing  the  order  in  which  LINK  processes  its  input  libraries. 


Code  segment 

EXTDEF  Label2 

jmpLabel2 

Modulel 


Code  segment: 

jmp  Label2 

Label2: 

Combined  code  segment 
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For  example,  imagine  that  a  C  programmer  has  written  two  versions  of  a  function  named 
myfuncQlYvaX  is  called  by  the  program  MYPROG.C.  One  version  of  myfuncO is  for 
debugging;  its  object  module  is  found  in  MYFUNC.OBJ.  The  other  is  a  production  version 
whose  object  module  resides  in  MYLIB.LIB.  Under  normal  circumstances,  the  program¬ 
mer  links  the  production  version  of  myfuncQhy  using  MYLIB.LIB  (Figure  20-5).  To  use 
the  debugging  version  of  myfuncCX  the  programmer  explicitly  includes  its  object  module 
(MYFUNC.OBJ)  when  LINK  is  executed.  This  causes  LINK  to  build  the  debugging  version 
of  myfuncO  into  the  executable  file  because  it  encounters  the  debugging  version  in 
MYFUNC.OBJ  before  it  finds  the  qther  version  in  MYLIB.LIB. 

To  exploit  the  order  in  which  LINK  resolves  external  references,  it  is  important  to  know 
LINK’S  library  search  strategy:  Each  individual  library  is  searched  repeatedly  (from  first 
library  to  last,  in  the  sequence  in  which  they  are  input  to  LINK)  until  no  further  external 
references  can  be  resolved. 


MYLIB.LIB 


Figure  20-5.  Ordered  object  module  processing  by  LINK,  (a)  With  the  command  LINK  MYPROG,„MYLIB, 
the  production  version  c/myfunc()  in  MYLIB. LIB  is  used,  (b)  With  the  command  LINK  MYPROG+ 
MYFUNC„,MYLIB,  the  debugging  version  ofmyixmcO  in  MYFUNC.OBJ  is  used. 
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ModuleA 

CallC 


ModuleB 


LIB1.LIB 


ModuleC 

ModuleMAIN 

CallB 

Call  A 

Lro2.LIB  MYPROG.OBJ 


Start  of 
program 


MYPROG.EXE 


ModuleMAIN 


ModuleA 


ModuleC 


ModuleB 


Figure  20-6.  Library  search  order.  Modules  are  incorporated  into  the  executable file  as  LINK  extracts  them 
from  the  libraries  to  resolve  external  references. 


The  example  in  Figure  20-6  demonstrates  this  search  strategy.  Library  LIBl.LIB  contains 
object  modules  A  and  B,  library  LIB2.LIB  contains  object  module  C,  and  the  object  file 
MYPROG.OBJ  contains  the  object  module  MAIN\  modules  MAIN,  A,  and  C  each  contain 
an  external  reference  to  a  symbol  declared  in  another  module.  When  this  program  is 
linked  with 

OLINK  MYPROG,  , ,  LIB1 +LIB2  <Enter> 

LINK  starts  by  incorporating  the  object  module  MAIN  into  the  executable  program.  It 
then  searches  the  input  libraries  until  it  resolves  all  the  external  references: 

1.  Process  MYPROG.OBJ,  find  unresolved  external  reference  to  A, 

2.  Search  LIBl.LIB,  extract  A,  find  unresolved  external  reference  to  C 

3.  Search  LIBl.LIB  again;  reference  to  Cremains  unresolved. 

4.  Search  LIB2.LIB,  extract  Q  find  unresolved  external  reference  to  B, 

5.  Search  LIB2.LIB  again;  reference  to  B  remains  unresolved. 

6.  Search  LIBl  .LIB  again,  extract  B, 

7.  No  more  unresolved  external  references,  so  end  library  search. 

The  order  in  which  the  modules  appear  in  the  executable  file  thus  reflects  the  order  in 
which  LINK  resolves  the  external  references;  this,  in  turn,  depends  on  which  modules 
were  contained  in  the  libraries  and  on  the  order  in  which  the  libraries  are  input  to  LINK. 

Name  of  the  executable  file 

If  no  filename  is  specified  in  the  command  line  or  in  response  to  the  Run  File  prompt, 
LINK  derives  the  name  of  the  executable  file  from  the  name  of  the  first  object  file  it  pro¬ 
cesses.  For  example,  if  the  object  files  PROGl.OBJ  and  PR0G2.0BJ  are  linked  with  the 
command 

OLINK  PR0G1+PR0G2;  <Enter> 

the  resulting  executable  file,  PROGl.EXE,  takes  its  name  from  the  first  object  file  pro¬ 
cessed  by  LINK. 
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Segment  Order  and  Segment  Combinations 

LINK  builds  segments  into  the  executable  file  by  applying  the  following  sequence  of  rules: 

1 .  Segments  appear  in  the  executable  file  in  the  order  in  which  their  SEGDEF  declara¬ 
tions  first  appear  in  the  input  object  modules. 

2.  Segments  in  different  object  modules  are  combined  if  they  have  the  same  name  and 
class  and  a  public,  memory,  stack,  or  common  combine  type.  All  address  references 
within  the  combined  segments  are  relocated  relative  to  the  start  of  the  combined 
segment. 

-  Segments  with  the  same  name  and  either  the  public  or  the  memory  combine  type 
are  combined  in  the  order  in  which  they  are  processed  by  LINK.  The  size  of  the 
resulting  segment  equals  the  total  size  of  the  combined  segments. 

-  Segments  with  the  same  name  and  the  stack  combine  type  are  overlapped  so  that 
the  data  in  each  of  the  overlapped  segments  ends  at  the  same  address.  The  size  of 
the  resulting  segment  equals  the  total  size  of  the  combined  segments.  The  resulting 
segment  is  always  paragraph  aligned. 

-  Segments  with  the  same  name  and  the  common  combine  type  are  overlapped  so 
that  the  data  in  each  of  the  overlapped  segments  starts  at  the  same  address.  The 
size  of  the  resulting  segment  equals  the  size  of  the  largest  of  the  overlapped 
segments. 

3.  Segments  with  the  same  class  name  are  concatenated. 

4.  If  the  /DOSSEG  switch  is  used,  the  segments  are  rearranged  in  conjunction  with 
DGROUP.  See  Using  the  /DOSSEG  Switch  below. 

These  rules  allow  the  programmer  to  control  the  organization  of  segments  in  the  execut¬ 
able  file  by  ordering  SEGMENT  declarations  in  an  assembly-language  source  module, 
which  produces  the  same  order  of  SEGDEF  records  in  the  corresponding  object  module, 
and  by  placing  this  object  module  first  in  the  order  in  which  LINK  processes  its  input  files. 

A  typical  MS-DOS  program  is  constructed  by  declaring  all  executable  code  and  data  seg¬ 
ments  with  the  public  combine  type,  thus  enabling  the  programmer  to  compile  the  pro¬ 
gram’s  source  code  from  separate  source-code  modules  into  separate  object  modules. 
When  these  object  modules  are  linked,  LINK  combines  the  segments  from  the  object 
modules  according  to  the  above  rules  to  create  logically  unified  code  and  data  segments 
in  the  executable  file. 

Segment  classes 

LINK  concatenates  segments  with  the  same  class  name  after  it  combines  segments  with 
the  same  segment  name  and  class.  For  example.  Figure  20-7  shows  the  following  compiling 
and  linking: 

OMASM  MYPR0G1;  <Enter> 

OMASM  MYPROG2;  <Enter> 

OLINK  MYPR0G1+MYPR0G2;  <Enter> 
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MYPROG2.ASM  MYPR0G2.0BJ 


Figure  20-7.  Segment  order  and  concatenation  by  LINK.  The  start  of  each  file,  corresponding  to  the  lowest 
address,  is  at  the  top. 

After  MYPROGl.ASM  and  MYPROG2.ASM  have  been  compiled,  LINK  builds  the  _TEXT 
and  FAR_TEXT  segments  by  combining  segments  with  the  same  name  from  the  different 
object  modules.  Then,  _TEXT  and  FAR_TEXT  are  concatenated  because  they  have  the 
same  class  name  (’CODE').  —TEXT  appears  before  FAR_TEXT  in  the  executable  file 
because  LINK  encounters  the  SEGDEF  record  for  _TEXT  before  it  finds  the  SEGDEF 
record  for  FAR_TEXT 

Segment  alignment 

LINK  aligns  the  starting  address  of  each  segment  it  processes  according  to  the  alignment 
specified  in  each  SEGDEF  record.  It  adjusts  the  alignment  of  each  segment  it  encounters 
regardless  of  how  that  segment  is  combined  with  other  segments  of  the  same  name  or 
class.  (The  one  exception  is  stack  segments,  which  always  start  on  a  paragraph 
boundary.) 


_DATA  SEGMENT  byte  public 

_DATA  SEGMENT  word  public 

_DATA  SEGMENT  para  public 

35H  bytes 

35H  bytes 

35H  bytes 

Module  1  Module2  ModuleS 


OOH 


35H 

36H 


6BH| 

70H 


Module  1 


Module2 


Module3 


Resulting  _DATA  segment  in  .EXE  file 


35H  bytes  (byte  aligned) 

35H  bytes  (word  aligned) 

35H  bytes  (paragraph  aligned) 


Figure  20-8.  Alignment  of  combined  segments.  LINK  enforces  segment  alignment  by  padding  combined 
segments  with  uninitialized  data  bytes. 
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Segment  alignment  is  particularly  important  when  public  segments  with  the  same  name 
and  class  are  combined  from  different  object  modules.  Note  what  happens  in  Figure  20-8, 
where  the  three  concatenated  ^DATA  segments  have  different  alignments.  To  enforce  the 
word  alignment  and  paragraph  alignment  of  the  ^DATA  segments  in  Module2  and 
Modules,  LINK  inserts  one  or  more  bytes  of  padding  between  the  segments. 

Segment  groups 

A  segment  group  establishes  a  logical  segment  address  to  which  all  offsets  in  a  group  of 
segments  can  refer.  That  is,  all  addresses  in  all  segments  in  the  group  can  be  expressed  as 
offsets  relative  to  the  segment  value  associated  with  the  group  (Figure  20-9).  Declaring 
segments  in  a  group  does  not  affect  their  positions  in  the  executable  file;  the  segments  in 
a  group  may  or  may  not  be  contiguous  and  can  appear  in  any  order  as  long  as  all  address 
references  to  the  group  fall  within  64  KB  of  each  other. 


DataGroup 

GROUP 

DataSegl , DataSeg2 

CodeSeg 

SEGMENT 

byte  public  *CODE* 

ASSUME 

cs : CodeSeg 

mov 

ax, offset  DataSeg2: TestData 

mov 

ax, offset  DataGroup : TestData 

CodeSeg 

ENDS 

DataSegl 

SEGMENT 

para  public  'DATA' 

DB 

lOOh  dup(?) 

DataSegl 

ENDS 

DataSeg2 

SEGMENT 

para  public  'DATA' 

TestData 

DB 

7 

DataSeg2 

ENDS 

END 

Figure  20-9.  Example  of  group  addressing.  The first  MOV  loads  the  value  OOH  into  AX  (the  offset  of  TestData 
relative  to  DataSeg2^/  the  second  MOV  loads  the  value  lOOH  into  AX  (the  offset  of  TestData  relative  to  the  group 
DataGroup^. 

LINK  reserves  one  group  name,  DGROUP,  for  use  by  Microsoft  language  translators. 
DGROUP  is  used  to  group  compiler-generated  data  segments  and  a  default  stack  segment. 
See  DGROUP  below. 


LINK  Internals 

Many  programmers  use  LINK  as  a  “black  box”  program  that  transforms  object  modules 
into  executable  files.  Nevertheless,  it  is  helpful  to  observe  how  LINK  processes  object 
records  to  accomplish  this  task. 
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LINK  is  a  two-pass  linker;  that  is,  it  reads  all  its  input  object  modules  twice.  On  Pass  1, 
LINK  builds  an  address  map  of  the  segments  and  symbols  in  the  object  modules.  On  Pass 
2,  it  extracts  the  executable  code  and  program  data  from  the  object  modules  and  builds 
a  memory  image — an  exact  replica — of  the  executable  file. 

The  reason  LINK  builds  an  image  of  the  executable  file  in  memory,  instead  of  simply 
copying  code  and  data  from  object  modules  into  the  executable  file,  is  that  it  organizes  the 
executable  file  by  segments  and  not  by  the  order  in  which  it  processes  object  modules. 

The  most  efficient  way  to  concatenate,  combine,  and  relocate  the  code  and  data  is  to  build 
a  map  of  the  executable  file  in  memory  during  Pass  1  and  then  fill  in  the  map  with  code 
and  data  during  Pass  2. 

In  versions  3-52  and  later,  whenever  the  /I  (/INFORMATION)  switch  is  specified  in  the 
command  line,  LINK  displays  status  messages  at  the  start  of  each  pass  and  as  it  processes 
each  object  module.  If  the  /M  (/MAP)  switch  is  used  in  addition  to  the  /I  switch,  LINK  also 
displays  the  total  length  of  each  segment  declared  in  the  object  modules.  This  information 
is  helpful  in  determining  how  the  structure  of  an  executable  file  corresponds  to  the  con¬ 
tents  of  the  object  modules  processed  by  LINK. 

Passl 

During  Pass  1,  LINK  processes  the  LNAMES,  SEGDEF,  GRPDEF,  COMDEF,  EXTDEF,  and 
PUBDEF  records  in  each  input  object  module  and  uses  the  information  in  these  object 
records  to  construct  a  symbol  table  and  an  address  map  of  segments  and  segment  groups. 

Symbol  table 

As  each  object  module  is  processed,  LINK  uses  the  symbol  table  to  resolve  external 
references  (declared  in  EXTDEF  and  COMDEF  records)  to  public  symbols.  If  LINK  pro¬ 
cesses  all  the  object  files  without  resolving  all  the  external  references  in  the  symbol  table, 
it  searches  the  input  libraries  for  public  symbols  that  match  the  unresolved  external 
references.  LINK  continues  to  search  each  library  until  all  the  external  references  in  the 
symbol  table  are  resolved. 

Segments  and  groups 

LINK  processes  each  SEGDEF  record  according  to  the  segment  name,  class  name,  and 
attributes  specified  in  the  record.  LINK  constructs  a  table  of  named  segments  and  updates 
it  as  it  concatenates  or  combines  segments.  This  allows  LINK  to  associate  each  public  sym¬ 
bol  in  the  symbol  table  with  an  offset  into  the  segment  in  which  the  symbol  is  declared. 

LINK  also  generates  default  segments  into  which  it  places  communal  variables  declared 
in  COMDEF  records.  Near  communal  variables  are  placed  in  one  paragraph-aligned  public 
segment  named  c_common,  with  class  name  BSS  (block  storage  space)  and  group 
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DGROUP.  Far  communal  variables  are  placed  in  a  paragraph-aligned  segment  named 
FAR_3SS,  with  class  name  FAR^BSS.  The  combine  type  of  each  far  communal  variable’s 
FARJ3SS  segment  is  private  (that  is,  not  public,  memory,  common,  or  stack).  As  many 
FARJBSS  segments  as  necessary  are  generated. 

After  all  the  object  files  have  been  read  and  all  the  external  references  in  the  symbol  table 
have  been  resolved,  LINK  has  a  complete  map  of  the  addresses  of  all  segments  and  sym¬ 
bols  in  the  program.  If  a  .MAP  file  has  been  requested,  LINK  creates  the  file  and  writes 
the  address  map  to  it.  Then  LINK  initiates  Pass  2. 

Pass  2 

In  Pass  2,  LINK  extracts  executable  code  and  program  data  from  the  LEDATA  and  LIDATA 
records  in  the  object  modules.  It  builds  the  code  and  data  into  a  memory  image  of  the 
executable  file.  During  Pass  2,  LINK  also  carries  out  all  the  address  relocations  and  fixups 
related  to  segment  relocation,  segment  grouping,  and  resolution  of  external  references,  as 
well  as  any  other  address  fixups  specified  explicitly  in  object  module  FEXUPP  records. 

If  it  determines  during  Pass  2  that  not  enough  RAM  is  available  to  contain  the  entire  image, 
LINK  creates  a  temporary  file  in  the  current  directory  on  the  default  disk  drive.  (LINK  ver¬ 
sions  3.60  and  later  use  the  environment  variable  TMP  to  find  the  directory  for  the  tempo¬ 
rary  scratch  file.)  LINK  then  uses  this  file  in  addition  to  all  the  available  RAM  to  construct 
the  image  of  the  executable  file.  (In  versions  of  MS-DOS  earlier  than  3.0,  the  temporary  file 
is  named  VM.TMP;  in  versions  3.0  and  later,  LINK  uses  Interrupt  21H  Function  5AH  to 
create  the  file.) 

LINK  reads  each  of  the  input  object  modules  in  the  same  order  as  it  did  in  Pass  1.  This  time 
it  copies  the  information  from  each  object  module’s  LEDATA  and  LIDATA  records  into  the 
memory  image  of  each  segment  in  the  proper  sequence.  This  is  when  LINK  expands  the 
iterated  data  in  each  LIDATA  record  it  processes. 

LINK  processes  each  LEDATA  and  LIDATA  record  along  with  the  corresponding  FDCUPP 
record,  if  one  exists.  LINK  processes  the  FDCUPP  record,  performs  the  address  calculations 
required  for  relocation,  segment  grouping,  and  resolving  external  references,  and  then 
stores  binary  data  from  the  LEDATA  or  LIDATA  record,  including  the  results  of  the  address 
calculations,  in  the  proper  segment  in  the  memory  image.  The  only  exception  to  this 
process  occurs  when  a  FDCUPP  record  refers  to  a  segment  address.  In  this  case,  LINK  adds 
the  address  of  the  fixup  to  a  table  of  segment  fixups;  this  table  is  used  later  to  generate  the 
segment  relocation  table  in  the  .EXE  header. 

When  all  the  data  has  been  extracted  from  the  object  modules  and  all  the  fixups  have 
been  carried  out,  the  memory  image  is  complete.  LINK  now  has  all  the  information  it 
needs  to  build  the  .EXE  header  (Table  20-1).  At  this  point,  therefore,  LINK  creates  the 
executable  file  and  writes  the  header  and  all  segments  into  it. 
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Table  20-1.  How  LINK  BuUds  a. EXE  FUe  Header. 


Offset  Contents 

OOH  'MZ' 

02H  Length  of  executable 

image  MOD  512 

04H  Length  of  executable  image  in 

512-byte  pages,  including  last 
partial  page  (if  any) 

06H  Number  of  run-time  segment 

relocations 

OSH  Size  of  the  .EXE  header  in  l6-byte 

paragraphs 

OAH  MINALLOC:  Minimum  amount  of 

RAM  to  be  allocated  above  end  of 
the  loaded  program  (in  l6-byte 
paragraphs) 

OCH  MAXALLOC:  Maximum  amount  of 

RAM  to  be  allocated  above  end 
of  the  loaded  program  (in  l6-byte 
paragraphs) 

OEH  Stack  segment  (initial  value  for  SS 

register);  relocated  by  MS-DOS 
when  program  is  loaded 

lOH  Stack  pointer  (initial  value  for 

register  SP) 

12H  Checksum 

14H  Entry  point  offset  (initial  value  for 

register  IP) 

16H  Entry  point  segment  (initial  value 

for  register  CS);  relocated  by 
MS-DOS  when  program  is  loaded  J 

18H  Offset  of  start  of  segment  relocation 

table  relative  to  start  of  .EXE 
header 

1  AH  Overlay  number 

ICH  Reserved 


Comments 

.EXE  file  signature 

I  Total  size  of  all  segments  plus  .EXE 
'  file  header 

Number  of  segment  fixups 

Size  of  segment  relocation  table 

Size  of  uninitialized  data  and/or  stack 
segments  at  end  of  program  (0  if  /HI 
switch  is  used) 

0  if  /HI  switch  is  used;  value  specified 
with  /CP  switch;  FFFFH  if /CP  and 
/HI  switches  are  not  used 

Address  of  stack  segment  relative  to 
start  of  executable  image 

Size  of  stack  segment  in  bytes 

One’s  complement  of  sum  of  all  words 
in  file,  excluding  checksum  itself 

I  MODEND  object  record  that  specifies 
^  program  start  address 


0  for  resident  segments;  >0  for  overlay 
segments 
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Using  LINK  to  Organize  Memory 


By  using  LINK  to  rearrange  and  combine  segments,  a  programmer  can  generate  an  exe¬ 
cutable  file  in  which  segment  order  and  addressing  serve  specific  purposes.  As  the  follow¬ 
ing  examples  demonstrate,  careful  use  of  LINK  leads  to  more  efficient  use  of  memory  and 
simpler,  more  efficient  programs. 

Segment  order  for  a  TSR 

In  a  terminate-and-stay-resident  (TSR)  program,  LINK  must  be  used  carefully  to  generate 
segments  in  the  executable  file  in  the  proper  order.  A  typical  TSR  program  consists  of  a 
resident  portion,  in  which  the  TSR  application  is  implemented,  and  a  transient  portion, 
which  executes  only  once  to  initialize  the  resident  portion.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Terminate-and-Stay-Resident  Utilities. 


Because  the  transient  portion  of  the  TSR  program  is  executed  only  once,  the  memory 
it  occupies  should  be  freed  after  the  resident  portion  has  been  initialized.  To  allow  the 
MS-DOS  Terminate  and  Stay  Resident  function  (Interrupt  21H  Function  31H)  to  free  this 
memory  when  it  leaves  the  resident  portion  of  the  TSR  program  in  memory,  the  TSR  pro¬ 
gram  must  have  its  resident  portion  at  lower  addresses  than  its  transient  portion. 


Low  Memory  ResidentCodeSeg 

ResidentCodeSeg 

ResidentDataSeg 

ResidentDataSeg 

StackSeg 

StackSeg 


SEGMENT  para 

.  (executable  code) 
ENDS 

SEGMENT  word 

. (program  data) 

ENDS 

SEGMENT  para 

.  (stack) 

ENDS 


Resident 

portion 


TransientCodeSeg  SEGMENT  para 

. (executable  code) 
TransientCodeSeg  ENDS 

TransientDataSeg  SEGMENT  word 

. (program  data) 

High  Memory  TransientDataSeg  ENDS 


Transient 

portion 


Figure  20-10.  Segment  order for  a  terminate-and-stay-resident  program. 
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In  Figure  20-10,  the  segments  containing  the  resident  code  and  data  are  declared  before 
the  segments  that  represent  the  transient  portion  of  the  program.  Because  LINK  preserves 
this  segment  order,  the  executable  program  has  the  desired  structure,  with  resident  code 
and  data  at  lower  addresses  than  transient  code  and  data.  Moreover,  the  number  of  para¬ 
graphs  in  the  resident  portion  of  the  program,  which  must  be  computed  before  Interrupt 
21H  Function  31H  is  called,  is  easy  to  derive  from  the  segment  structure:  This  value  is  the 
difference  between  the  segment  address  of  the  program  segment  prefix,  which  immedi¬ 
ately  precedes  the  first  segment  in  the  resident  portion,  and  the  address  of  the  first  seg¬ 
ment  in  the  transient  portion  of  the  program. 

Groups  for  unified  segment  addressing 

In  some  programs  it  is  desirable  to  maintain  executable  code  and  data  in  separate  logical 
segments  but  to  address  both  code  and  data  with  the  same  segment  register.  For  example, 
in  a  hardware  interrupt  handler,  using  the  CS  register  to  address  program  data  is  generally 
simpler  than  using  DS  or  ES. 

In  the  routine  in  Figure  20-11,  code  and  data  are  maintained  in  separate  segments  for  pro¬ 
gram  clarity,  yet  both  can  be  addressed  using  the  CS  register  because  both  code  and  data 
segments  are  included  in  the  same  group.  (The  SNAP.ASM  listing  in  the  Terminate-and- 
Stay-Resident  Utilities  article  is  another  example  of  this  use  of  a  group  to  unify  segment 
addressing.) 


ISRgroup 

GROUP 

CodeSeg, DataSeg 

CodeSeg 

SEGMENT 

byte  public  *C0DE* 

ASSUME 

cs: ISRgroup 

mov 

ax, offset  ISRgroup: CodeLabel 

CodeLabel : 

mov 

bx, ISRgroup: DataLabel 

CodeSeg 

ENDS 

DataSeg 

SEGMENT 

para  public  'DATA' 

DataLabel 

DW 

? 

DataSeg 

ENDS 

END 

Figure  20-11.  Code  and  data  included  in  the  same  group.  In  this  example,  addresses  within  both  CodeSeg 
and  DataSeg  are  referenced  relative  to  the  CS  register  by  grouping  the  segments  (using  the  assembler  GROUP 
directive)  and  addressing  the  group  through  CS  (using  the  assembler  ASSUME  directive). 

Uninitialized  data  segments 

A  segment  that  contains  only  uninitialized  data  can  be  processed  by  LINK  in  two  ways, 
depending  on  the  position  of  the  segment  in  the  program.  If  the  segment  is  not  at  the  end 
of  the  program,  LINK  generates  a  block  of  bytes  initialized  to  zero  to  represent  the  seg¬ 
ment  in  the  executable  file.  If  the  segment  appears  at  the  end  of  the  program,  however, 
LINK  does  not  generate  a  block  of  zeroed  bytes.  Instead,  it  increases  the  minimum  run¬ 
time  memory  allocation  by  increasing  MINALLOC  (specified  at  offset  OAH  in  the  .EXE 
header)  by  the  amount  of  memory  required  for  the  segment. 
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Therefore,  if  it  is  necessary  to  reserve  a  large  amount  of  uninitialized  memory  in  a  seg¬ 
ment,  the  size  of  the  .EXE  file  can  be  decreased  by  building  the  segment  at  the  end  of  a 
program  (Figure  20-12).  This  is  why,  for  example,  Microsoft  high-level-language  translators 
always  build  BSS  and  STACK  segments  at  the  end  of  compiled  programs.  (The  loader  does 
not  fill  these  segments  with  zeros;  a  program  must  still  initialize  them  with  appropriate 
values.) 


CodeSeg 

SEGMENT 

byte  public  'CODE' 

ASSUME 

ret 

cs : CodeSeg, ds ; DataSeg 

CodeSeg 

ENDS 

DataSeg 

SEGMENT 

word  public  'DATA' 

BigBuffer 

DB 

10000  dup(?) 

DataSeg 

ENDS 

END 

DataSeg 

SEGMENT 

word  public  'DATA' 

BigBuffer 

DB 

10000  dup(?) 

DataSeg 

ENDS 

CodeSeg 

SEGMENT 

byte  public  'CODE' 

ASSUME 

ret 

cs : CodeSeg, ds : DataSeg 

CodeSeg 

ENDS 

END 

Figure  20-12.  LINK  processing  of  uninitialized  data  segments,  (a)  When  DataSeg,  which  contains  only 
uninitialized  data,  is  placed  at  the  end  of  this  program,  the  size  of  the  .EXE file  is  only  513  bytes,  (b)  When 
DataSeg  is  not  placed  at  the  end  of  the  program,  the  size  of  the  .EXE file  is  10513  bytes. 

Overlays 

If  a  program  contains  two  or  more  subroutines  that  are  mutually  independent — that  is, 
subroutines  that  do  not  transfer  control  to  each  other — LINK  can  be  instructed  to  build 
each  subroutine  into  a  separately  loaded  portion  of  the  executable  file.  (This  instruction 
is  indicated  in  the  command  line  when  LINK  is  executed  by  enclosing  each  overlay  sub¬ 
routine  or  group  of  subroutines  in  parentheses.)  Each  of  the  subroutines  can  then  be  over¬ 
laid  as  it  is  needed  in  the  same  area  of  memory  (Figure  20-13).  The  amount  of  memory 
required  to  run  a  program  that  uses  overlays  is,  therefore,  less  than  the  amount  required 
to  run  the  same  program  without  overlays. 

A  program  that  uses  overlays  must  include  the  Microsoft  run-time  overlay  manager.  The 
overlay  manager  is  responsible  for  copying  overlay  code  from  the  executable  file  into 
memory  whenever  the  program  attempts  to  transfer  control  to  code  in  an  overlay.  A  pro¬ 
gram  that  uses  overlays  runs  slower  than  a  program  that  does  not  use  them,  because  it 
takes  longer  to  extract  overlays  separately  from  the  .EXE  file  than  it  does  to  read  the  entire 
.EXE  file  into  memory  at  once. 
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(a) 


LINK  A+B+C+D+E;  LINK  A+(B+C)+(D+E); 


Figure  20-13.  Memory  use  in  a  program  linked  (a)  without  overlays  and  (b)  with  overlays.  In  (b),  either 
modules  (B+C)  or  modules  (D+E)  can  be  loaded  into  the  overlay  area  at  run  time. 

The  default  object  libraries  that  accompany  Microsoft  high-level-language  compilers  con¬ 
tain  object  modules  that  support  the  Microsoft  run-time  overlay  manager.  The  following 
description  of  LINK’S  relationship  to  the  run-time  overlay  manager  applies  to  versions 
3.00  through  3.60  of  LINK;  implementation  details  may  vary  in  future  versions. 

Overlay  format  in  a  .EXE  file 

An  executable  file  that  contains  overlays  has  a  .EXE  header  preceding  each  overlay  (Figure 
20-14).  The  overlays  are  numbered  in  sequence,  starting  at  0;  the  overlay  number  is  stored 
in  the  word  at  offset  lAH  in  each  overlay’s  .EXE  header.  When  the  contents  of  the  .EXE  file 
are  loaded  into  memory  for  execution,  only  the  resident,  nonoverlaid  part  of  the  program 
is  copied  into  memory.  The  overlays  must  be  read  into  memory  from  the  .EXE  file  by  the 
run-time  overlay  manager. 


Overlay  number  0 


Overlay  number  1 


Overlay  number  2 


Figure  20-14.  .EXE file  structure  produced  by  LINK  A  +  (B+C)  +  (D+E) . 
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Segments  for  overlays 

When  LINK  produces  an  executable  file  that  contains  overlays,  it  adds  three  segments 
to  those  defined  in  the  object  modules:  OVERLAYLAREA,  OVF.RT.AY  END  and 
OVERLAY_DATA.  LINK  assigns  the  segment  class  name  'CODE'  to  OVERLAY_AREA 
and  OVERLAY_END  and  includes  OVERLAY_DATA  in  the  default  group  DGROUR 

OVERLAY_AREA  is  a  reserved  segment  into  which  the  run-time  overlay  manager  is 
expected  to  load  each  overlay  as  it  is  needed.  Therefore,  LINK  sets  the  size  of 
OVERLAY_AREA  to  fit  the  largest  overlay  in  the  program.  The  OVERLAY_END  seg¬ 
ment  is  declared  immediately  after  OVERLAY_AREA,  so  a  program  can  determine  the 
size  of  the  OVERLAY_AREA  segment  by  subtracting  its  segment  address  from  that  of 
OVERLAY-END.  The  OVERLAY-DATA  segment  is  initialized  by  LINK  with  information 
about  the  executable  file,  the  number  of  overlays,  and  other  data  useful  to  the  run-time 
overlay  manager. 

LINK  requires  the  executable  code  used  in  overlays  to  be  contained  in  segments  whose 
class  names  end  in  CODE  and  whose  segment  names  differ  from  those  of  the  segments 
used  in  the  resident  (nonoverlaid)  portion  of  the  program.  In  assembly  language,  this  is 
accomplished  by  using  the  SEGMENT  directive;  in  high-level  languages,  the  technique  of 
ensuring  unique  segment  names  depends  on  the  compiler.  In  Microsoft  C,  for  example,  the 
A  switch  in  the  command  line  selects  the  memory  model  and  thus  the  segment  naming 
defaults  used  by  the  compiler;  in  medium,  laige,  and  huge  memory  models,  the  compiler 
generates  a  unique  segment  name  for  each  C  function  in  the  source  code.  In  Microsoft 
FORTRAN,  on  the  other  hand,  the  compiler  always  generates  a  uniquely  named  segment 
for  each  SUBROUTINE  and  FUNCTION  in  the  source  code,  so  no  special  programming 
is  required. 

LINK  substitutes  all  far  CALL  instructions  from  root  to  overlay  or  from  overlay  to 
overlay  with  a  software  interrupt  followed  by  an  overlay  number  and  an  offset  into  the 
overlay  segment  (Figure  20-15).  The  interrupt  number  can  be  specified  with  LINK’S 
/OVERLAYINTERRUPT  switch;  if  the  switch  is  omitted,  LINK  uses  Interrupt  3FH  by 
default.  By  replacing  calls  to  overlay  code  with  a  software  interrupt,  LINK  provides  a 
mechanism  for  the  run-time  overlay  manager  to  take  control,  load  a  specified  overlay 
into  memory,  and  transfer  control  to  a  specified  offset  within  the  overlay. 


(a) 

EXTRN 

OverlayEntryPoint : far 

call 

OverlayEntryPoint 

far  CALL 

(b) 

int 

IntNo 

interrupt  number 

specified  with  /OVERLAYINTERRUPT 
switch  (default  3FH) 

DB 

OverlayNumber  ; 

overlay  number 

DW 

OverlayEntry  ; 

offset  of  overlay  entry  point 

;  (the  address  to  which 
;  the  overlay  manager  transfers 
;  control) 

Figure20-15.  Executable  code  modification  by  LINK  for  accessing  overlays,  (a)  Code  as  written.  (b)Codeas 
modified  by  LINK. 
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Run-time  processing  of  overlays 

The  resident  (nonoverlaid)  portion  of  a  program  that  uses  overlays  initializes  the  overlay 
interrupt  vector  specified  by  LINK  with  the  address  of  the  run-time  overlay  manager.  (The 
OVERLAY_DATA  segment  contains  the  interrupt  number.)  The  overlay  manager  then 
takes  control  wherever  LINK  has  substituted  a  software  interrupt  for  a  far  call  in  the  exe¬ 
cutable  code. 

Each  time  the  overlay  manager  executes,  its  first  task  is  to  determine  which  overlay  is 
being  called.  It  does  this  by  using  the  return  address  left  on  the  stack  by  the  INT  instruc¬ 
tion  that  invoked  the  overlay  manager;  this  address  points  to  the  overlay  number  stored  in 
the  byte  after  the  interrupt  instruction  that  just  executed.  The  overlay  manager  then  deter¬ 
mines  whether  the  destination  overlay  is  already  resident  and  loads  it  only  if  necessary. 
Next,  the  overlay  manager  opens  the  .EXE  file,  using  the  filename  in  the  OVERLAY-  DATA 
segment.  It  locates  the  start  of  the  specified  overlay  in  the  file  by  examining  the  length 
(offset  02H  and  offset  04H)  and  overlay  number  (offset  lAH)  in  each  overlay’s  .EXE 
header. 

The  overlay  manager  can  then  read  the  overlay  from  the  .EXE  file  into  the 
OVERLAY_AREA  segment.  It  uses  the  overlay’s  segment  relocation  table  to  fix  up  any  seg¬ 
ment  references  in  the  overlay.  The  overlay  manager  transfers  control  to  the  overlay  with  a 
far  call  to  the  OVERLAY_AREA  segment,  using  the  offset  stored  by  LINK  1  byte  after  the 
interrupt  instruction  (.see  Figure  20-15). 

Interrupt  21H  Function  4BH 

LINK’S  protocol  for  implementing  overlays  is  not  recognized  by  Interrupt  21H  Function 
4BH  (Load  and  Execute  Program).  This  MS-DOS  function,  when  called  with  AL  =  03H, 
loads  an  overlay  from  a  .EXE  file  into  a  specified  location  in  memory.  See  SYSTEM  CALLS: 
Interrupt  21h:  Function  4BH.  However,  Function  4BH  does  not  use  an  overlay  number,  so 
it  cannot  find  overlays  in  a  .EXE  file  formatted  by  LINK  with  multiple  .EXE  headers. 

DGROUP 

LINK  always  includes  DGROUP  in  its  internal  table  of  segment  groups.  In  object  modules 
generated  by  Microsoft  high-level-language  translators,  DGROUP  contains  both  the  default 
data  segment  and  the  stack  segment.  LINK’S  /DOSSEG  and  /DSALLOCATE  switches  both 
affect  the  way  LINK  treats  DGROUP.  Changing  the  way  LINK  manages  DGROUP  ulti¬ 
mately  affects  segment  order  and  addressing  in  the  executable  file. 

Using  the  /DOSSEG  switch 

The  /DOSSEG  switch  causes  LINK  to  arrange  segments  in  the  default  order  used  by 
Microsoft  high-level-language  translators: 

1 .  All  segments  with  a  class  name  ending  in  CODE.  These  segments  contain  executable 
code. 

2.  All  other  segments  outside  DGROUP.  These  segments  typically  contain  far  data  items. 
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3.  DGROUP  segments.  These  are  a  program’s  near  data  and  stack  segments.  The  order 
in  which  segments  appear  in  DGROUP  is 

-  Any  segments  of  class  BEGDATA.  (This  class  name  is  reserved  for  Microsoft  use.) 

-  Any  segments  not  of  class  BEGDATA,  BSS,  or  STACK. 

-  Segments  of  class  BSS. 

-  Segments  of  class  STACK. 

This  segment  order  is  necessary  if  programs  compiled  by  Microsoft  translators  are  to  run 
properly.  The  /DOSSEG  switch  can  be  used  whenever  an  object  module  produced  by  an 
assembler  is  linked  ahead  of  object  modules  generated  by  a  Microsoft  compiler,  to  ensure 
that  segments  in  the  executable  file  are  ordered  as  in  the  preceding  list  regardless  of  the 
order  of  segments  in  the  assembled  object  module. 

When  the  /DOSSEG  switch  is  in  effect,  LINK  always  places  DGROUP  at  the  end  of  the 
executable  program,  with  all  uninitalized  data  segments  at  the  end  of  the  group.  As  dis¬ 
cussed  above,  this  placement  helps  to  minimize  the  size  of  the  executable  file.  The 
/DOSSEG  switch  also  causes  LINK  to  restructure  the  executable  program  to  support 
certain  conventions  used  by  Microsoft  language  translators: 

•  Compiler-generated  segments  with  the  class  name  BEGDATA  are  placed  at  the  begin¬ 
ning  of  DGROUP. 

•  The  public  symbols  _edata  and  _end  are  generated  to  point  to  the  beginning  of  the 
BSS  and  STACK  segments. 

•  Sixteen  bytes  of  zero  are  inserted  in  front  of  the  _TEXT  segment. 

Microsoft  compilers  that  rely  on  /DOSSEG  conventions  generate  a  special  COMENT  object 
record  that  sets  the  /DOSSEG  switch  when  the  record  is  processed  by  LINK. 

Using  the  /HIGH  and  /DSALLOCATE  switches 

When  a  program  has  been  linked  without  using  LINK’S  /HIGH  switch,  MS-DOS  loads 
program  code  and  data  segments  from  the  .EXE  file  at  the  lowest  address  in  the  first  avail¬ 
able  block  of  RAM  large  enough  to  contain  the  program  (Figure  20-16).  The  value  in  the 
.EXE  header  at  offset  OCH  specifies  the  maximum  amount  of  extra  RAM  MS-DOS  must 
allocate  to  the  program  above  what  is  loaded  from  the  .EXE  file.  Above  that,  all  unused 
RAM  is  managed  by  MS-DOS.  With  this  memory  allocation  strategy,  a  program  can  use 
Interrupt  21H  Functions  48H  (Allocate  Memory  Block)  and  4AH  (Resize  Memory  Block) 
to  increase  or  decrease  the  amount  of  RAM  allocated  to  it. 

When  a  program  is  linked  with  LINK’S  /HIGH  switch,  LINK  zeros  the  words  it  stores  in 
the  .EXE  header  at  offset  OAH  and  OCH.  Setting  the  words  at  OAH  and  OCH  to  zero  indi¬ 
cates  that  the  program  is  to  be  loaded  into  RAM  at  the  highest  address  possible  (Figure 
20-16).  With  this  memory  layout,  however,  a  program  can  no  longer  change  its  memory 
allocation  dynamically  because  all  available  RAM  is  allocated  to  the  program  when  it  is 
loaded  and  the  uninitialized  RAM  between  the  program  segment  prefix  and  the  program 
itself  cannot  be  freed. 
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Program  code  and 
data  segments 
copied  from  .EXE  file 


Figure  2(F16.  Effect  of  the /HIGH  switch  on  run-time  memory  use.  (a)  The  program  is  linked  without  the 
/HIGH  switch,  (b)  The  program  is  linked  with  the /HIGH  switch. 


The  only  reason  to  load  a  program  with  this  type  of  memory  allocation  is  to  allow  a  pro¬ 
gram  data  structure  to  be  dynamically  extended  toward  lower  memory  addresses.  For 
example,  both  stacks  and  heaps  can  be  implemented  in  this  way.  If  a  program’s  stack 
segment  is  the  first  segment  in  its  memory  map,  the  stack  can  grow  downward  without 
colliding  with  other  program  data. 

To  facilitate  addressing  in  such  a  segment,  LINK  provides  the  /DSALLOCATE  switch. 

When  a  program  is  linked  using  this  switch,  all  addresses  within  DGROUP  are  relocated  in 
such  a  way  that  the  last  byte  in  the  group  has  offset  FFFFH.  For  example,  if  the  program  in 
Figure  20-17  is  linked  without  the  /DSALLOCATE  and  /HIGH  switches,  the  value  of  offset 
DGROUP:DataItem  would  be  OOH;  if  these  switches  are  used,  the  linker  adjusts  the  seg¬ 
ment  value  of  DGROUP  downward  so  that  the  offset  of  Dataltem  within  DGROUP 
becomes  FFFOH. 

Early  versions  of  Microsoft  Pascal  (before  version  3  30)  and  Microsoft  FORTRAN  (before 
version  3.30)  generated  object  code  that  had  to  be  linked  with  the  /DSALLOCATE  switch. 
For  this  reason,  LINK  sets  the  /DSALLOCATE  switch  by  default  if  it  processes  an  object 
module  containing  a  COMENT  record  generated  by  one  of  these  compilers.  (Such  a 
COMENT  record  contains  the  string  MS  PASCAL  or  FORTRAN  77.  See  PROGRAMMING 
IN  THE  MS-DOS  ENVIRONMENT:  Prcxjramming  Tools:  Object  Modules.)  Apart  from  this 
special  requirement  of  certain  language  translators,  however,  the  use  of  /DSALLOCATE 
and  /HIGH  should  probably  be  avoided  because  of  the  limitations  they  place  on  run-time 
memory  allocation. 
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DGROUP 

GROUP 

-DATA 

-DATA 

SEGMENT 

word  public  *DATA* 

Dataltem 

DB 

1 0h  dup  (?) 

-DATA 

ENDS 

-TEXT 

SEGMENT 

byte  public  *CODE* 

ASSUME 

c  s ; -TEXT , ds : DGROUP 

mov 

bx, offset  DGROUP: Dataltem 

-TEXT 

ENDS 

END 

Figure  20-1 7.  The  value  of  offset  DGROUP:DataItem  in  this  program  is  FFFOH  if  the  program  is  linked  with 
the /DSALLOC ATE  switch  or  OOH  if  the  program  is  linked  without  using  the  switch. 


Summary 

LINK’S  characteristic  support  for  segment  ordering,  for  run-time  memory  management, 
and  for  dynamic  overlays  has  an  impact  in  many  different  situations.  Programmers  who 
write  their  own  language  translators  must  bear  in  mind  the  special  conventions  followed 
by  LINK  in  support  of  Microsoft  language  translators.  Application  programmers  must  be 
familiar  with  LINK’S  capabilities  when  they  use  assembly  language  or  link  assembly-lan¬ 
guage  programs  with  object  modules  generated  by  Microsoft  compilers.  LINK  is  a  power¬ 
ful  program  development  tool  and  understanding  its  special  capabilities  can  lead 
to  more  efficient  programs. 


Richard  Wilton 
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User  Commands  Introduction 


Introduction 


This  section  of  The  MS-DOS  Encyclopedia  describes  the  standard  internal  and  external 
MS-DOS  commands  available  to  the  user  who  is  running  MS-DOS  (versions  1.0  through 
3.2).  System  configuration  options,  special  batch-file  directives,  the  line  editor  (EDLIN), 
and  the  installable  device  drivers  normally  included  with  MS-DOS  are  also  covered. 

Entries  are  arranged  alphabetically  by  the  name  of  the  command  or  driver.  The  config¬ 
uration,  batch-file,  and  line-editor  directives  appear  alphabetically  under  the  headings 
CONFIG.SYS,  BATCH,  and  EDLIN,  respectively.  Each  entry  includes 

•  Command  name 

•  Version  dependencies  and  network  information 

•  Command  purpose 

•  Prototype  command  and  summary  of  options 

•  Detailed  description  of  command 

•  One  or  more  examples  of  command  use 

•  Return  codes  (where  applicable) 

•  Informational  and  error  messages 

The  experienced  user  can  find  information  with  a  quick  glance  at  the  first  part  of  a  com¬ 
mand  entry;  a  less  experienced  user  can  refer  to  the  detailed  explanation  and  examples  in 
a  more  leisurely  fashion.  The  next  two  pages  contain  an  example  of  a  typical  entry  from 
the  User  Commands  section,  with  explanations  of  each  component.  This  example  is 
followed  by  listings  of  the  commands  by  functional  group. 

The  following  terms  are  used  for  command-line  variables  in  the  sample  syntax: 

drive  a  letter  in  the  range  A-Z,  followed  by  a  colon,  indicating  a  logical  disk 

drive. 

path  a  specific  location  in  a  disk’s  hierarchical  directory  structure;  can  include 

the  special  directory  names  .  and  .. ;  elements  are  separated  by  backslash 
characters  (\). 

pathname  a  file  specification  that  can  include  a  path  and/or  drive  and/or  filename 

extension. 

filename  the  name  of  a  file,  generally  with  its  extension;  cannot  include  a  drive  or 

path. 

Note:  PC-DOS,  though  not  an  official  product  name,  is  used  in  this  section  to  indicate 
IBM’s  version  of  the  disk  operating  system  originally  provided  by  Microsoft.  Commands 
sometimes  have  slightly  different  options  or  appear  for  the  first  time  in  different  versions 
of  MS-DOS  and  PC-DOS.  When  a  command  appears  only  in  the  IBM  versions,  the  abbre¬ 
viation  IBM  appears  in  the  heading  area.  Significant  differences  between  MS-DOS  and 
PC-DOS  versions  of  a  command  are  indicated  in  the  Syntax  and  Description  portions 
of  the  entry. 
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HEADING - 

The  command  name  as 
the  user  would  enter  it 
or  as  it  would  be  used 
in  a  batch  or  system- 
configuration  file. 

ICON-1 - 

MS-DOS  version 
dependency. 

ICON-2 - 

Whether  the  command 
is  internal  (built  into 
COMMAND.COM)  or 
external  (loaded  from  a 
disk  file  when  needed). 

ICON-3 _ 

The  abbreviation  IBM  if 
the  command  is  present 
only  in  PC-DOS  and  the 
warning  No  Net  if  the 
command  cannot  be 
used  across  a  network. 

PURPOSE - 

An  abstract  of  command 
purpose  and  usage. 

SYNTAX _ 

A  prototype  command 
line,  with  variable  names 
in  italic  and  optional 
parameters  in  square 
brackets.  The  various 
elements  of  the  com¬ 
mand  line  should  be 
entered  in  the  order 
shown.  Any  punctuation 
must  be  used  exactly  as 
shown;  in  commands 
that  use  commas  as 
separators,  the  comma 
usually  must  be  included 
as  a  placeholder  even  if 
the  parameter  is  omit¬ 
ted.  Except  where  noted, 
commands,  parameters, 
and  switches  can  be 
entered  in  either  upper¬ 
case  or  lowercase.  With 
MS-DOS  versions  3.0 
and  later,  external  com¬ 
mands  can  be  preceded 
by  a  drive  and/or  path. 


REPLACE 

update  Files 


3.2 

^^^/Exiernal 


^  Purpose 

Selectively  adds  or  replaces  files  on  a  disk. 

Syntax 

J  REPLACE  Idrfwdpo/Aname  \drive^\path\  I/All/Dll/Pil/RH/Sll/W) 
where: 


pathname 

drive-.path 


/A 


/P 

/R 

/S 


is  the  name  and  location  of  the  source  Hies  to^  transferred,  optionally 
preceded  by  a  drive;  wildcard  characters  ajuf^rmitted  in  the  filename, 
is  the  destination  for  the  file  being  trans^ed;  filenames  are  not  permit¬ 
ted  in  the  destination  parameter, 

transfers  only  those  source  files  th^o  not  exist  at  the  destination  (cannot 
be  used  with  /S  or  /D). 

transfers  only  those  source  fjld^  Mth  a  more  recent  date  than  their  destina¬ 
tion  counterparts  (cannot^usi  d  with  A). 

Iirmatii  n  before  each  file  is  transferred, 
ite  di  stination  read-only  files, 
of  th  :  destination  directory  for  a  match  with 
Iwith  A). 


prompts  the  user  for  i 
allows  REPLACE  to 
searches  all 
the  source  nie&<<cannot  be  used! 


pesciiptlon 


The  REPLACE  utility  allows  files  to  be  updated  i 
examines  the  source  and  destination  directories! 
the  command  line,  selectively  updates  matching 
on  the  SQur^  disk  but  not  the  destination.disk. 


epathw^ 


The 
transferred 
drive-.path 
andean 
REPLACE 
ted  compleifey, 
REPLACE  t<| 
replaced 


parameter  (the  destination)  specifies  the 
of  a  drive,  a  path,  or  both.  If  only  a  dm 
imes  the  current  directory  of  the  dislpm  thaj 


The/A./D, 
When  the  /\ 
not  exist  in 


914  TheMS-tX^Axyebyfedia 


to  wait  for  the  hisk  to  be  changed  before  transferring 


^ily  to  more  recent  versions.  REPLACE 
jand,  depending  on  thyiWtches  used  in 
files  or  copies  only  t^e  files  that  exist 


param^er  (the  source)  specifies  the  name  anc^cation  of  the  files  to  be 
[optionally  preceded  by  a  drive);  wildcards  are,permitted  in  the  filename.  The 


ton  of  the  files  to  be  replaced 
specified  as  the  destination, 
drive.  If  the  destination  is  omit- 


REPLACE  assumes  the  current  ^ 
also  search  all  subdirectories  of 


e  and  Jirectory.  The  /S  switch  causes 


[ibn  directory  for  files  to  be 


^d/P  switches  allow selanive  replacement 
switch  is  used  REPLA(2E  transfers  only  thost 
[he  destination  direjlt^.  When  the  /D  switclj 


qf  files  on  the  destination  disk, 
files  on  the  source  disk  that  do 
is  used  REPLACE  transfers  only 


BELOW  WHERE 
A  brief  explanation  of 
each  command  parame¬ 
ter  and  switch.  Drives, 
paths,  and  filenames  are 
always  listed  first,  fol¬ 
lowed  by  the  switches  in 
alphabetic  order.  Any 
special  position  required 
for  a  filename  or  switch 
is  shown  in  the  syntax 
line  and  noted  in  the 
explanation. 


DESCRIPTION 
A  detailed  description  of 
the  command,  including 
a  full  explanation  of 
MS-DOS  version  depen¬ 
dencies,  default  values, 
possible  interactions  of 
command  parameters 
and  options,  useful 
background  information, 
and  any  applicable 
warnings. 
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:fie  destination  filenames  but  have  a  more  recent  date  than 
(The  /D  switch  is  not  available  with  the  PC-DOS  version  of 
REPLACE  to  prompt  the  user  for  confirmation  before 


4E 


The  /W  switch  causes  REPLA<^ 
b^inning  the  transfer  of  flles.|' 
with  no  Hxed  disk  and  in  those 
neither  the  source  nor  the  desf 


Return  Codes 


15 

Other 


those  source  files  that  match  tl 
their  destination  counterparts]' 

REPLACE.)  The  /P  switch 
each  file  is  transferred 

The  /R  switch  allows  the  reph  cement  of  read-only  as  well  as  normal  files.  If  the  /R  switch 
is  not  used  and  one  of  the  diu  ii 
read-only,  the  REPLACE  prcigi  am 
used  to  update  hidden  or  sysu  m 


to  pause  a| 
[This  allows 
cases  wher4 
[ination  disk. 


ijid  wait  for  the  user  to  press  any  key  before 
user  to  change  dislu  in  floppy-disk  systems 
the  REPLACE  program  itself  is  present  on 


The  REPLACE  op^tion 
An  error  was  founA  in 
No  matching  files  found  b} 
The  source  or  desAnation  path 
One  of  the  fil^w  be  replaced 
not  include^i^n  the  ctxnmand  li 
Memoryw&  insufficient  to  run| 
An  inv^  drive  was  specified 

d  MS-DOS  error  codes  (iei 


iful. 

'LIACE  command  line. 


Examples 


c^JCTcplacedTSTiiaikcd” 


[ination  files 

im  terminates  with  an  error  message.  (REPLACE  cannot  be 
|m  files.) 


^  invalid  or  does  not  exist. 

marked  read-only  and  the  /R  switch  was 


lihe. 

pie  REPLACE  command, 
the  command  line. 

:tumed  on  a  failed  Interrupt  21H  file-function 


To  replace  the  files  in  the  directory  \SOUR<  E  on  current  drive  with  all  matching  files 
on  the  disk  in  drive  A  that  have  a  mote  recc  it  djtfe,  type 


OREPLACE  A:*.*  \SOURCE  /D  <Enter> 

To  transfer  from  the  disk  in  drive  A  oidyUtose  files  thaj  are  not  already  present  in  the  cur¬ 
rent  directory,  type 


OREPLACE  A;*. 


A  <Encar>  / 


ffFlleCs)  added 

After  the  replacement  operation  is  completed,  if  the  /A  switch^^  used  in  the  command 
line,  REPLACE  displays  the  total  number  of  fil^adrted  / 

n  Flle(s)  replaced 

After  the  replacement  operation  is  completed,  REPL/TCE  displays  the  total  number  of  files 
processed.  / 
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-  RETURN  CODES 
Exit  codes  returned  by 
the  command  (if  any) 
that  can  be  tested  in  a 
batch  file  or  by  another 
program. 

-  EXAMPLES 

One  or  more  examples 
of  the  command  at  work, 
including  examples  of 
the  resulting  output 
where  appropriate.  User 
entry  appears  in  color; 
do  not  type  the  prompt, 
which  appears  in  black. 
Press  the  Enter  key 
(labeled  Return  on  some 
keyboards)  as  directed 
at  the  end  of  each 
command  line. 

-  MESSAGES 

An  alphabetic  list  of 
messages  that  may  be 
displayed  when  the 
command  is  used  in 
MS-DOS  version  3.2 
(may  vary  slightly  in 
earlier  versions).  Both 
messages  generated  by 
the  command  itself  and 
applicable  messages  gen¬ 
erated  by  MS-DOS  are 
included.  Following  each 
message  is  a  brief 
explanation  of  the  con¬ 
dition  that  produces  the 
message  and,  where 
appropriate,  any  action 
that  should  be  taken. 
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Contents  by  Functional  Group 

The  MS-DOS  commands  can  be  divided  into  several  distinct  groups  according  to  the  func¬ 
tions  they  perform.  These  are  listed  on  the  following  pages. 


Command 

Action 

S^tem  Configuration  and  Control 

BREAK 

Set  Control-C  check. 

COMMAND 

Install  secondary  copy  of  command  processor. 

DATE 

Set  date. 

EXIT 

Terminate  command  processor. 

PROMPT 

Define  system  prompt. 

SELECT 

Configure  system  disk  for  a  specific  country. 

SET 

Set  environment  variable. 

SHARE 

Install  file-sharing  support. 

TIME 

Set  system  time. 

VER 

Display  version. 

Character-Device  Maiu^ement 

CIS 

Clear  screen. 

CTTY 

Assign  standard  input/output. 

GRAFTABL 

Load  graphics  character  set. 

GRAPHICS 

Print  graphics  screen-dump  program. 

KEYBjca: 

Define  keyboard. 

MODE 

Configure  device. 

PRINT 

Print  file  (background  print  spooler). 

File  Management 

ATTRIB 

Change  file  attributes. 

BACKUP 

Back  up  files. 

COMP 

Compare  files. 

COPY 

Copy  file  or  device. 

DEL/ERASE 

Delete  file. 

EDLIN 

Create  or  modify  text  file  (see  also  commands  below). 

FC 

Compare  files. 

RECOVER 

Recover  files. 

RENAME 

Change  filename. 

REPLACE 

Update  files. 

RESTORE 

Restore  backup  files. 

TYPE 

Display  file. 

XCOPY 

Copy  files. 

(more) 
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Command 

Action 

Filters 

FIND 

Find  string. 

MORE 

Display  by  screenful. 

SORT 

Sort  file  or  character  stream  alphabetically. 

Directory  Management 

APPEND 

Set  data-file  search  path. 

CHDIR 

Change  current  directory. 

DIR 

Display  directory. 

MKDIR 

Make  directory. 

PATH 

Define  command  search  path. 

RMDIR 

Remove  directory. 

TREE 

Display  directory  structure. 

Disk  Management 

ASSIGN 

Assign  drive  alias. 

CHKDSK 

Check  disk  status. 

DISKCOMP 

Compare  floppy  disks. 

DISKCOPY 

Copy  floppy  disks. 

FORMAT 

Initialize  disk. 

FDISK 

Configure  fixed  disk. 

JOIN 

Join  disk  to  directory. 

LABEL 

Display  volume  label. 

SUBST 

Substitute  drive  for  subdirectory. 

SYS 

Transfer  system  files. 

VERIFY 

Set  verify  flag. 

VOL 

Display  disk  name. 

Installable  Device  Drivers 

ANSI.SYS 

ANSI  console  driver. 

DRIVER.SYS 

Configurable  external-disk-drive  driver. 

RAMDRIVE.SYS 

Virtual  disk. 

VDISK.SYS 

Virtual  disk. 

System-Configuration  File  Directives 


BREAK 

BUFFERS 

COUNTRY 

DEVICE 

DRIVPARM 

FCBS 


Configure  Control-C  checking. 

Configure  internal  disk  buffers. 

Set  country  code. 

Install  device  driver. 

Set  block-device  parameters. 

Set  maximum  open  files  using  File  Control  Blocks  (FCBs). 


(more) 
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Command 

Action 

System-Configuration  File  Directives  (continued) 

FILES 

Set  maximum  open  files  using  handles. 

LASTDRIVE 

Set  highest  logical  drive. 

SHELL 

Specify  command  processor. 

STACKS 

Configure  internal  stacks. 

Batch-File  Directives 

AUTOEXEC.BAT 

System  startup  batch  file. 

ECHO 

Display  text. 

FOR 

Execute  command  on  file  set. 

GOTO 

Jump  to  label. 

IF 

Perform  conditional  execution. 

PAUSE 

Suspend  batch-file  execution. 

REM 

Include  comment  line. 

SHIFT 

Shift  replaceable  parameters. 

EDLIN  Commands 

linenumber 

Edit  line. 

A 

Append  lines  from  disk. 

c 

Copy  lines. 

D 

Delete  lines. 

E 

End  editing  session. 

I 

Insert  lines. 

L 

List  lines. 

M 

Move  lines. 

P 

Display  in  pages. 

Q 

Quit. 

R 

Replace  text. 

S 

Search  for  text. 

T 

Transfer  another  file. 

W 

Write  lines  to  disk. 
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ANSLSYS  2.0  and  later 

ANSI  Console  Driver  External 


Purpose 

Allows  the  user  to  employ  a  subset  of  the  American  National  Standards  Institute  (ANSI) 
standard  escape  sequences  for  control  of  the  console. 

Syntax 

DEVICE=[^/nz;^:]  [p^^/^lANSI.SYS 
where: 

drive\path  is  the  drive  and/or  path  to  search  for  ANSI.SYS  if  it  is  not  in  the  root  direc¬ 

tory  of  the  startup  disk. 

Description 

The  ANSI.SYS  file  contains  an  installable  character-device  driver  that  supersedes  the 
system’s  default  driver  for  the  console  device  (video  display  and  keyboard).  After 
ANSI.SYS  is  installed  by  means  of  a  DEVICE=ANSLSYS  command  in  the  CONFIG.SYS  file 
of  the  disk  used  to  start  the  system,  programs  can  use  a  subset  of  the  ANSI  3.64-1979  stan¬ 
dard  escape  sequences  to  erase  the  display,  set  the  display  mode  and  attributes,  and  con¬ 
trol  the  cursor  in  a  hardware-independent  fashion.  (A  supplementary  set  of  escape 
sequences  that  are  not  part  of  the  ANSI  standard  allows  reprogramming  of  the  keyboard.) 

Programs  that  use  ANSI.SYS  for  control  of  the  screen  can  run  on  any  MS-DOS  machine 
without  modification,  regardless  of  its  hardware  configuration.  However,  most  popular  ap¬ 
plication  programs  for  the  IBM  PC  and  compatibles  circumvent  ANSI.SYS  and  manipulate 
the  video  controller  and  its  video  buffer  directly  to  achieve  maximum  performance. 

The  ANSI.SYS  device  driver  detects  ANSI  escape  sequences  in  a  character  stream  and 
interprets  them  as  commands  to  control  the  keyboard  and  display.  An  ANSI  escape  se¬ 
quence  is  a  sequence  of  ASCII  characters,  the  first  two  of  which  must  be  the  Escape  char¬ 
acter  (IBH)  and  the  left-bracket  character  (5BH).  The  characters  following  the  Escape  and 
left-bracket  characters  vary  with  the  type  of  control  function  being  performed;  most  con¬ 
sist  of  an  alphanumeric  code  followed  by  a  letter.  In  some  cases  this  code  is  a  single  char¬ 
acter;  in  others  it  is  more  than  one  character  or  a  two-part  string  separated  by  a  semicolon. 
Each  ANSI  escape  sequence  ends  in  a  unique  letter  character  that  identifies  the  sequence; 
case  is  significant  for  these  letters.  The  escape  sequences  supported  by  the  ANSI.SYS 
driver  are  summarized  in  the  tables  on  the  following  pages. 

An  escape  sequence  cannot  be  entered  directly  at  the  system  prompt  because  each  ANSI 
escape  sequence  must  begin  with  an  Escape  character,  and  pressing  the  Esc  key  (or  Alt-27 
on  the  numeric  keypad)  causes  MS-DOS  to  cancel  the  command  line.  There  are  three 
methods  of  executing  ANSI  escape  sequences  that  do  not  require  writing  a  program: 
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•  Include  the  escape  sequences  in  a  PROMPT  command. 

•  Enter  the  escape  sequences  into  a  word  processor  or  text  editor,  save  the  file  as  an 
ASCII  text  file,  and  then  execute  the  file  by  using  the  TYPE  or  COPY  command  (spec¬ 
ifying  CON  as  the  destination  for  COPY)  from  the  MS-DOS  system  prompt. 

(If  the  escape  sequences  are  echoed  on  the  screen  when  the  file  is  executed,  a 
DEVICE= ANSI.SYS  command  was  not  included  in  the  CONFIG.SYS  file  when  the 
system  was  turned  on.) 

•  Place  the  escape  sequences  in  a  batch  (.BAT)  file  as  part  of  an  ECHO  command. 
When  the  batch  file  is  executed,  the  sequences  are  sent  to  the  console. 

When  escape  sequences  are  entered  using  the  PROMPT  command,  the  Escape  character 
is  entered  as  $e.  When  escape  sequences  are  entered  using  a  word  processor  to  create  an 
ASCII  text  or  batch  file,  the  Escape  character  is  usually  entered  by  pressing  the  Esc  key  or 
by  holding  down  the  Alt  key  while  typing  27  on  the  numeric  keypad.  (See  the  documenta¬ 
tion  provided  with  the  word-processor  for  specific  instructions.)  In  most  cases,  the  escape 
character  will  appear  in  the  word  processor  or  text  editor  as  a  back-arrow  character  (<— ) 
or  a  caret-left  bracket  combination  (^[). 

Note:  When  the  escape  character  is  represented  as  (as  it  is  in  EDLIN,  for  example),  an 
additional  left-bracket  character  must  still  be  added  to  properly  begin  an  ANSI  escape  se¬ 
quence.  Thus,  the  beginning  of  a  valid  ANSI  escape  sequence  in  EDLIN  appears  as  ^[[. 

The  tables  in  this  section  use  the  abbreviation  ESC  to  show  where  the  ASCII  escape  char¬ 
acter  27  (IBH)  appears  in  the  string. 

Note:  Case  is  significant  for  the  terminal  character  in  the  string. 

The  following  escape  sequences  control  cursor  movement: 


Operation 

Escape  Sequence 

Effect 

Cursor  Up 

"ESQlnumberK 

Moves  the  cursor  up  number  rows  (1-24, 
default  =  1).  Has  no  effect  if  cursor  is  on 
the  top  row. 

Cursor  Down 

YSC[numberB 

Moves  the  cursor  down  number  rows 
(1-24,  default  =  1).  Has  no  effect  if  cursor 
is  on  the  bottom  row. 

Cursor  Right 

YSCinumberC 

Moves  the  cursor  right  number  rows  (1-79, 
default  =  1).  Has  no  effect  if  cursor  is  in 
the  far  right  column. 

Cursor  Left 

ESC[numberD 

Moves  the  cursor  left  number  rows  (1-79, 
default  =  1).  Has  no  effect  if  cursor  is  in 
the  far  left  column. 

Position  Cursor 

ESC[rot^;;  columnH 

Moves  the  cursor  to  the  specified  row 
(1-25,  default  =  1)  and  column  (1-80, 
default  =  1).  If  row  is  omitted,  the  semi¬ 
colon  before  column  must  be  specified. 

(more) 
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Operation 

Escape  Sequence 

Effect 

Position  Cursor 

^SC[row-,columnf 

Same  as  above. 

Save  Cursor  Position 

ESC[s 

Stores  the  current  row  and  column  position 
of  the  cursor.  Cursor  can  be  restored  to 
this  position  later  with  a  Restore  Cursor 
Position  escape  sequence. 

Restore  Cursor 

Position 

ESC[u 

Moves  the  cursor  to  the  position  of  the 
most  recent  Save  Cursor  Position  escape 
sequence. 

The  following  two  escape  sequences  are  used  to  erase  all  or  part  of  the  display: 

Operation 

Escape  Sequence 

Effect 

Erase  Display 

ESC[2J 

Clears  the  screen  and  places  the  cursor  at 
the  home  position. 

Erase  Line 

ESC[K 

Erases  from  the  cursor  position  to  the  end 

of  the  same  row. 


The  following  escape  sequences  control  the  width  and  the  color  capability  of  the  display. 
The  use  of  any  of  these  sequences  clears  the  screen. 


Operation 

Escape  Sequence 

Effect 

Set  Mode 

ESChOh 

Sets  display  to  40  x  25  monochrome  (text). 

ESC[=lh 

Sets  display  to  40  x  25  color  (text). 

ESC(=2h 

Sets  display  to  80  x  25  monochrome  (text). 

ESC[=3h 

Sets  display  to  80  x  25  color  (text). 

ESC[=4h 

Sets  display  to  320  x  200  4-color  (graphics). 

ESC[=5h 

Sets  display  to  320  x  200  4-color  (graphics, 

color  burst  disabled). 

ESC[=6h 

Sets  display  to  640  x  200  2-color  (graphics). 

The  following  escape  sequences  control  whether  characters  will  wrap  around  to  the  first 
column  of  the  next  row  after  the  rightmost  column  in  the  current  row  has  been  filled: 

Operation 

Escape  Sequence 

Effect 

Enable  Character 

ESC[=7h 

Sets  character  wrap. 

Wrap 

Disable  Character 

ESC[=71 

Disables  character  wrap.  (Note  that  the 

Wrap 

terminating  letter  is  a  lowercase  L.) 
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The  following  escape  sequence  controls  specific  graphics  attributes  such  as  intensity, 
blinking,  superscript,  and  subscript,  as  well  as  the  foreground  and  background  colors: 

ESC[attrib\ . . .  ;attribm 

where: 

attrib  is  one  or  more  of  the  following  values.  Multiple  values  must  be  separated  by 
semicolons. 


Value 

Attribute 

Value 

Foreground 

Color 

Value 

Background 

Color 

0 

All  attributes  off 

30 

Black 

40 

Black 

1 

High  intensity  (bold) 

31 

Red 

41 

Red 

2 

Normal  intensity 

32 

Green 

42 

Green 

4 

Underline  (mono¬ 

chrome  only) 

33 

Yellow 

43 

Yellow 

5 

Blink 

34 

Blue 

44 

Blue 

7 

Reverse  video 

35 

Magenta 

45 

Magenta 

8 

Concealed  (invisible) 

36 

Cyan 

46 

Cyan 

37 

White 

47 

White 

Note:  Values  30  through  47  meet  the  ISO  6429  standard. 

The  following  escape  sequence  allows  redefinition  of  keyboard  keys  to  a  specified  string: 

ESC[code\string\ . . .  p 

where: 

code  is  one  or  more  of  the  following  values  that  represent  keyboard  keys. 

Semicolons  shown  in  this  table  must  be  entered  in  addition  to  the  required 
semicolons  in  the  command  line. 

string  is  either  the  ASCII  code  for  a  single  character  or  a  string  contained  in  quotation 

marks.  For  example,  both  65  and  "A”  can  be  used  to  represent  an  uppercase  A. 


Key 

Code 

Alone 

Shift- 

Ctrl- 

Alt- 

FI 

0;59 

0;84 

0;94 

0;104 

F2 

0;60 

0;85 

0;95 

0;105 

F3 

0;6l 

0;86 

0;96 

0;106 

F4 

0;62 

0;87 

0;97 

0;107 

F5 

0;63 

0;88 

0;98 

0;108 

F6 

0;64 

0;89 

0;99 

0;109 

(more) 
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Key 

Code 

Alone 

Shift- 

Ctrl- 

Alt- 

F7 

0;65 

0;90 

0;100 

0;110 

F8 

0;66 

0;91 

0;101 

0;111 

F9 

0;67 

0;92 

0;102 

0;112 

FIO 

0;68 

0;93 

0;103 

0;113 

Home 

0;71 

55 

0;119 

- 

Up  Arrow 

0;72 

56 

- 

- 

PgUp 

0;73 

57 

0;132 

- 

Left  Arrow 

0;75 

52 

0;115 

- 

Down  Arrow 

0;77 

54 

0;116 

- 

End 

0;79 

49 

0;117 

- 

Down  Arrow 

0;80 

50 

- 

- 

Pg  Dn 

0;81 

51 

0;118 

- 

Ins 

0;82 

48 

- 

- 

Del 

0;83 

46 

- 

- 

PrtSc 

- 

- 

0;114 

— 

A 

97 

65 

1 

0;30 

B 

98 

66 

2 

0;48 

C 

99 

67 

3 

0;46 

D 

100 

68 

4 

0;32 

E 

101 

69 

5 

0;18 

F 

102 

70 

6 

0;33 

G 

103 

71 

7 

0;34 

H 

104 

72 

8 

0;35 

I 

105 

73 

9 

0;23 

J 

106 

74 

10 

0;36 

K 

107 

75 

11 

0;37 

L 

108 

76 

12 

0;38 

M 

109 

77 

13 

0;50 

N 

110 

78 

14 

0;49 

O 

111 

79 

15 

0;24 

P 

112 

80 

16 

0;25 

Q 

113 

81 

17 

0;16 

R 

114 

82 

18 

0;19 

S 

115 

83 

19 

0;31 

T 

116 

84 

20 

0;20 

U 

117 

85 

21 

0;22 

V 

118 

86 

22 

0;47 

W 

119 

87 

23 

0;17 

X 

120 

88 

24 

0;45 

(more) 
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Key 

Code 

Alone 

Shift- 

Ctrl- 

Alt- 

Y 

121 

89 

25 

0;21 

Z 

122 

90 

26 

0;44 

1 

49 

33 

- 

0;120 

2 

50 

64 

- 

0;121 

3 

51 

35 

- 

0;122 

4 

52 

36 

- 

0;123 

5 

53 

37 

- 

0;124 

6 

54 

94 

- 

0;125 

7 

55 

38 

- 

0;126 

8 

56 

42 

- 

0;127 

9 

57 

40 

- 

0;128 

0 

48 

41 

- 

0;129 

- 

45 

95 

- 

0;130 

= 

61 

43 

- 

0;131 

Tab 

9 

0;15 

- 

- 

Null 

0;3 

- 

- 

- 

Examples 

The  following  examples  use  ESC  or  $e  to  show  where  the  ASCII  escape  character  27  (IBH) 
appears  in  the  string.  The  PROMPT  examples  can  be  typed  as  shown,  but  for  the  examples 
that  use  ESC  to  denote  the  escape  character,  the  actual  escape  character  should  be  typed  in 
its  place. 

To  move  the  cursor  to  row  10,  column  30  and  display  the  string  Main  Menu,  use  the  escape 
sequence 

ESC[ 1 0; 30fMain  Menu 

or 

ESC[10;30HMain  Menu 

To  move  the  cursor  to  row  5,  column  10  and  display  the  letter  A  iESC[5;10fA),  move  the 
cursor  down  one  row  (E'567B),  move  the  cursor  back  one  space  and  display  the  letter  B 
iESC[DE),  move  the  cursor  down  one  row  iESCfB),  and  move  the  cursor  back  one  space 
and  display  the  letter  C  (ESC/DC),  use  the  escape  sequence 

ESC [ 5 ; 1 0  f AESC [ BESC [ DBESC [ BESC [ DC 

To  use  ANSI  escape  sequences  with  the  PROMPT  command  to  save  the  current  cursor 
position  move  the  cursor  to  row  1,  column  69  i$e[l;69fX  display  the  current  time 
using  the  PROMPT  command’s  $t  function,  restore  the  cursor  position  and  then 
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display  the  current  path  using  the  PROMPT  command’s  $p  function  and  display  a  greater- 
than  sign  using  the  PROMPT  command’s  $g  function,  use  the  escape  sequence 

C>PROMPT  $e[s$e[1 ;69f$t$e[u$p$g  <Enter> 

To  erase  the  display  iESC[2J)y  then  move  the  cursor  to  row  10,  column  30  and  display  the 
string  Main  Menu  iESC[10;30fMain  Menu),  use  the  escape  sequence 

ESC[2JESC[10;30fMain  Menu 

To  move  the  cursor  to  row  5,  column  40  CESC[5;40f)  and  erase  the  remainder  of  the  row 
starting  at  the  current  cursor  position  CESCfK),  use  the  escape  sequence 

ESC[5;40fESC[K 

To  move  the  cursor  to  row  3  iESC[3; /),  erase  the  entire  row  iESC[K),  move  the  cursor 
down  one  row  iESC[E),  erase  that  entire  row  iESC[K),  move  the  cursor  down  one  row  and 
erase  that  entire  row,  use  the  escape  sequence 

ESC [ 3 ; f ESC [ KESC [ BESC [ KESC [ BESC [ K 

To  set  the  display  mode  to  25  rows  of  80  columns  in  color  CESCf=3h)  and  disable  character 
wrap  CESCf=  71),  use  the  escape  sequence 

ESC[=3hESC[=71 

Note  that  ESC[=3h  will  also  clear  the  screen. 

To  enable  character  wrap,  use  the  escape  sequence 

ESC[=7h 

To  set  the  foreground  color  to  black  and  the  background  color  to  blue  iESC[30;44m),  clear 
the  display  iESC[2J),  then  position  the  cursor  at  row  10,  column  30  and  display  the  string 
Main  Menu  iMSC[10;30fMain  Menu),  use  the  escape  sequence 

ESC[30;44mESC[2JESC[10;30fMain  Menu 

To  (effectively)  exchange  the  backslash  and  question-mark  keys  using  literal  strings  to 
denote  the  keys,  use  the  escape  sequence 


ESC [ " \ " ; " ? "pESC [ " ? ” ; " \ "p 

To  exchange  the  backslash  and  question-mark  keys  using  each  key’s  ASCII  value  to  denote 
the  key,  use  the  escape  sequence 

ESC[92;63pESC[63;92p 

To  restore  the  backslash  and  question-mark  keys  to  their  original  meanings,  use  the  escape 
sequence 


ESC  [ "  \  '• ;  ”  \  "pESC  [ "  ?  " ;  "  ?  "p 


or 

ESC [ 92 ; 92pESC [ 63 ; 63p 
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To  redefine  the  Alt-F9  key  combination  iESClO;ll2)  so  that  it  issues  a  CIS  command 
(;"6Z5")  plus  a  carriage  return  (;i3)  to  execute  the  CIS  command,  then  issues  a  DIR  com¬ 
mand  piped  through  the  SORT  filter  starting  at  column  24  (;  ''DIR  1  SORT /+24"')  followed 
by  another  carriage  return,  use  the  escape  sequence 

ESC[0;1 12;"CLS";13;"DIR  !  SORT  /+24”;13p 

To  restore  the  Alt-F9  key  combination  to  its  original  meaning,  use  the  escape  sequence 

ESC [ 0 ; 1 1 2 ; 0 ; 1 1 2p 
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APPEND 

Set  Data-File  Search  Path 


3.2 

External 


Purpose 

Specifies  a  search  path  for  open  operations  on  data  files.  (Also  supported  with  some 
implementations  of  version  3.1,  for  use  with  networks.) 

Syntax 

APPEND  [[drive] path]  [\drive] path  . . .  ] 
or 

APPEND ; 
where: 

path  is  the  name  of  a  valid  directory,  optionally  preceded  by  a  drive. 

Description 

APPEND  is  a  terminate-and-stay-resident  program  that  is  used  to  specify  a  path  or  paths  to 
be  searched  for  data  files  (in  contrast  with  the  PATH  command,  which  specifies  a  path  to 
be  searched  for  executable  or  batch  files).  The  search  path  can  include  a  network  drive.  If 
a  program  attempts  to  open  a  file  and  the  file  is  not  found  in  the  current  or  specified  direc¬ 
tory,  each  path  given  in  the  APPEND  command  is  searched. 

If  the  APPEND  command  is  entered  with  a  path  consisting  of  only  a  semicolon  character 
(;),  a  “null”  search  path  for  data  files  is  set;  that  is,  no  directory  other  than  the  current  or 
specified  directory  is  searched.  This  effectively  cancels  any  search  paths  previously  set 
with  an  APPEND  command  but  does  not  free  the  memory  used  by  APPEND. 

An  APPEND  command  without  any  parameters  displays  the  current  search  path(s)  for  data 
files. 

Note  that  a  program  cannot  detect  whether  an  opened  file  was  found  where  it  was  ex¬ 
pected  (in  the  current  or  specified  directory)  or  in  some  other  directory  specified  in  the 
APPEND  command. 

Warning:  When  an  assigned  drive  is  to  be  part  of  the  search  path,  the  ASSIGN  command 
must  be  used  before  the  APPEND  command.  Use  of  the  ASSIGN  command  should  be 
avoided  whenever  possible  because  it  hides  drive  characteristics  from  those  programs  that 
require  detailed  knowledge  of  the  drive  size  and  format. 
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Examples 

To  cause  the  directories  C:\SYSTEM  and  C:\SOURCE  to  be  searched  for  a  file  during  an 
open  operation  if  the  file  is  not  found  in  the  current  or  specified  directory,  type 

C>APPEND  C:\SYSTEM; C:\SOURCE  <Enter> 

To  display  the  current  search  path  for  data  files,  type 

C>APPEND  <Enter> 

MS-DOS  then  displays 

APPEND=C : \SYSTEM; C : \SOURCE 

To  ensure  that  no  directories  other  than  the  current  or  specified  directory  are  searched 
during  a  file  open  operation,  type 

C>APPEND  ;  <Enter> 

Messages 

APPEND  /  ASSIGN  Conflict 

APPEND  was  used  before  ASSIGN. 

Incorrect  DOS  version 

The  version  of  APPEND  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

No  appended  directories 

The  APPEND  command  had  no  parameters  and  no  APPEND  search  path  is  active. 
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ASSIGN  3.0  and  later 

Assign  Drive  Alias  External 


Purpose 

Redirects  requests  for  disk  operations  on  one  drive  to  a  different  drive.  (Available  with 
PC-DOS  beginning  with  version  2.0.) 

Syntax 

ASSIGN [...]] 
where: 

X  is  a  valid  designator  (A,  B,  C,  etc.)  for  a  disk  drive  that  physically  exists  in  the 

system. 

y  is  a  valid  designator  for  the  drive  to  be  accessed  by  references  to  x. 

Description 

ASSIGN  is  a  terminate-and-stay-resident  program  that  redirects  all  references  to  drive  a:  or 
files  on  drive  x  to  drive  y.  The  ASSIGN  command  is  intended  for  use  with  application  pro¬ 
grams  that  require  files  to  reside  on  drive  A  or  B  and  have  no  provision  within  the  pro¬ 
gram  for  changing  those  drives. 

Multiple  drive  assignments  can  be  requested  in  the  same  ASSIGN  command  line;  the  drive 
pairs  must  be  separated  with  spaces,  commas,  or  semicolons.  Unlike  the  form  in  most 
other  MS-DOS  commands,  the  drive  letters  are  not  followed  by  colon  characters  (:).  When 
a  single  drive  is  assigned,  the  equal  sign  is  optional. 

ASSIGN  commands  are  not  incremental.  Each  new  ASSIGN  command  replaces  assign¬ 
ments  made  with  the  previous  ASSIGN  command  and  cancels  any  assignments  not  specifi¬ 
cally  replaced.  Entering  ASSIGN  with  no  parameters  cancels  all  current  drive  assignments. 

Warning:  Use  of  the  ASSIGN  command  should  be  avoided  whenever  possible  because  it 
hides  drive  characteristics  from  those  programs  that  require  detailed  knowledge  of  the 
drive  size  and  format;  in  particular,  drives  redirected  with  an  ASSIGN  statement  should 
never  be  used  with  a  BACKUP,  RESTORE,  LABEL,  JOIN,  SUBST,  or  PRINT  command. 
ASSIGN  can  also  defeat  the  checking  performed  by  the  COPY  command  to  prevent  a  file 
from  being  copied  onto  itself.  The  FORMAT,  SYS,  DISKCOPY,  and  DISKCOMP  commands 
ignore  any  drive  reassignments  made  with  ASSIGN. 

With  MS-DOS  versions  3.1  and  later,  the  SUBST  command  should  be  used  instead  of 
ASSIGN.  For  example,  the  command 

OASSIGN  A=C  <Enter> 

9 

should  be  replaced  with  the  command 

C>SUBST  A:  C:\  <Enter> 
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Examples 

To  redirect  all  requests  for  drive  A  to  drive  C,  type 

C>ASSIGN  A=C  <Enter> 

To  redirect  all  requests  for  drives  A  and  B  to  drive  C,  type 

C>ASSIGN  A=C  B=C  <Enter> 

To  cancel  all  drive  redirections  currently  in  effect,  type 

C>ASSIGN  <Enter> 

Messages 

Incorrect  DOS  version 

The  version  of  ASSIGN  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Invalid  parameter 

One  of  the  specified  drive  designators  refers  to  a  drive  that  does  not  exist  in  the  system. 
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ATXRIB  3.0  and  later 

Change  File  Attributes  External 


Purpose 

Sets,  removes,  or  displays  a  file’s  read-only  and/or  archive  attributes. 

Syntax 

ATTRIB  (+R 1  -R  ]  [+A 1-A]  [drive]  pathname 
where: 

+R  marks  the  file  read-only. 

-R  removes  the  read-only  attribute. 

+A  sets  the  file’s  archive  flag  (version  3.2). 

-A  removes  the  file’s  archive  flag  (version  3-2). 

pathname  is  the  name  and  location,  optionally  preceded  by  a  drive,  of  the  file  whose 

attributes  are  to  be  changed  or  displayed;  wildcard  characters  are  permitted  in 
the  filename. 

Description 

Each  file  has  an  entry  in  the  disk’s  directory  that  contains  its  name,  location,  and  size;  the 
date  and  time  it  was  created  or  last  modified;  and  an  attribute  byte.  For  normal  files,  bits  0, 
1, 2,  and  5  in  the  attribute  byte  designate,  respectively,  whether  the  file  is  read-only,  hid¬ 
den,  or  system  and  whether  it  has  been  changed  since  it  was  last  backed  up. 

The  ATTRIB  command  provides  a  way  to  alter  the  read-only  and  archive  bits  from  the 
MS-DOS  command  level.  If  a  file  is  marked  read-only,  it  cannot  be  deleted  or  modified; 
thus,  crucial  programs  or  data  can  be  protected  from  accidental  erasure.  A  file’s  archive 
flag  can  be  used  together  with  the  /M  switch  of  the  BACKUP  command  or  the  /M  or  /A 
switch  of  the  XCOPY  command  to  allow  an  incremental  or  selective  backup  of  files  from 
one  disk  to  another. 

If  the  ATTRIB  command  is  entered  with  only  a  pathname,  the  current  attributes  of  the 
selected  file  are  displayed.  An  R  is  displayed  next  to  the  name  of  a  file  that  is  marked  read¬ 
only  and  an  A  is  displayed  if  the  file  has  the  archive  flag  set. 

Examples 

To  make  the  file  MENUMGR.C  in  the  current  directory  of  the  current  drive  a  read-only  file, 
type 

C>ATTRIB  +R  MENUMGR.C  <Enter> 

To  display  the  attributes  of  the  file  LETTER.DOC  in  the  directory  \  SOURCE  on  the  disk  in 
drive  D,  type 

C>ATTRIB  D:\SOURCE\LETTER.DOC  <Enter> 
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MS-DOS  then  displays 

R  A  D:\SOURCE\LETTER.DOC 

to  indicate  that  the  file  is  marked  read-only  and  the  archive  flag  has  been  set. 

To  set  the  archive  flag  on  all  files  in  the  directory  \  SYSTEM  on  drive  C  and  mark  them  as 
read-only,  type 

OATTRIB  +A  +R  C;\SYSTEM\*.  *  <Enter> 

Messages 

Access  denied 

ATTRIB  cannot  be  used  to  alter  or  replace  the  attributes  of  a  file  in  use  across  a  network. 

DOS  2.0  or  later  required 

ATTRIB  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Incorrect  DOS  version 

The  version  of  ATTRIB  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Invalid  number  of  parameters 

More  than  two  attributes  were  used  before  the  pathname. 

Invalid  path  or  file  not  found 

The  file  named  in  the  command  line  or  one  of  the  directories  in  the  given  path  does  not 
exist. 

Syntax  error 

An  invalid  attribute  was  supplied  or  the  attribute  was  not  properly  placed  before  the  path¬ 
name  in  the  command  line. 
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Back  Up  Files 


2.0  and  later 
External 


Purpose 

Creates  backup  copies  of  files,  along  with  the  associated  directory  information  necessary 
to  restore  the  files  to  their  original  locations. 

Syntax 

BACKUP  source  destination  [/A]  [/D-.date]  [/L:  filename]  [/M]  [/P]  [/S]  [/T.time] 
where: 


is  the  location  (drive  and/or  path)  and,  optionally,  the  name  of  the  files  to 
be  backed  up;  wildcard  characters  are  permitted  in  the  filename, 
is  the  drive  to  receive  the  backup  files. 

adds  the  files  to  existing  files  on  the  destination  disk  without  erasing  the 
destination  disk. 

backs  up  only  those  files  modified  on  or  after  date. 
creates  a  log  file  with  the  specified  name  in  the  root  directory  of  the 
disk  being  backed  up.  If  filename  is  not  specified,  BACKUP  creates  a 
file  named  BACKUP.LCXj  and  places  the  log  entries  there.  Use  of  the 
/h.  filename  switch  may  cause  loss  of  IBM  compatibility, 
backs  up  only  those  files  modified  since  the  last  backup, 
packs  the  destination  disk  with  as  many  files  as  possible,  creating  sub¬ 
directories,  if  necessary,  to  hold  some  of  the  files.  Use  of  the  /P  switch 
causes  loss  of  IBM  compatibility. 

backs  up  the  contents  of  all  subdirectories  of  the  source  directory. 

/T :  time  backs  up  only  those  files  modified  on  or  after  time. 

Note:  Not  all  switches  are  supported  by  all  implementations  of  MS-DOS. 

Description 

The  BACKUP  command  creates  a  backup  copy  of  the  specified  file  or  files,  transferring 
them  from  either  a  floppy  disk  or  a  fixed  disk  to  another  removable  or  fixed  disk.  The 
backup  file  is  in  a  special  format  that  includes  information  about  the  original  file’s  location 
in  the  directory  structure.  Files  created  by  BACKUP  can  be  restored  to  their  original  form 
only  with  the  RESTORE  command. 


source 

destination 

/A 

/D:date 
/L:  filename 


/M 

/P 


BACKUP  can  back  up  a  single  file  or  many  files  in  the  same  operation.  If  only  a  drive  letter 
is  given  as  the  source,  all  the  files  in  the  current  directory  of  that  disk  are  backed  up.  If 
only  a  path  is  given  as  the  source,  all  the  files  in  the  specified  directory  are  backed  up.  If 
the  /S  switch  is  used,  all  the  files  in  the  current  or  specified  directory  are  backed  up,  and 


Section  III:  User  Commands  745 


BACKUP 


the  files  in  all  its  subdirectories  as  well.  If  both  a  path  and  a  filename  are  entered  as  the 
source,  the  specified  file  or  files  in  the  named  directory  are  backed  up. 

If  the  source  file  is  marked  read-only,  the  resulting  backup  file  will  also  be  marked  read¬ 
only.  If  the  source  file’s  archive  bit  is  set,  it  will  be  cleared  for  both  the  source  and  the  des¬ 
tination  files.  BACKUP  also  backs  up  hidden  files;  the  files  will  remain  hidden  on  the  desti¬ 
nation  disk. 

If  the  destination  disk  is  a  floppy  disk,  its  previous  contents  are  erased  as  part  of  the 
backup  operation  (unless  the  /h.  switch  is  included  in  the  command  line  and  the  destina¬ 
tion  disk  has  already  been  used  as  a  backup  disk — that  is,  the  disk  contains  a  valid 
BACKUPID.@@@  file).  If  the  files  being  backed  up  do  not  fit  onto  a  single  floppy  disk,  the 
user  will  be  prompted  to  insert  additional  disks  until  the  backup  operation  is  complete. 

If  the  destination  disk  is  a  fixed  disk,  the  backed-up  files  are  placed  in  a  directory  named 
NBACKUP.  If  a  \BACKUP  directory  already  exists  on  the  fixed  disk,  any  files  previously 
contained  in  it  are  erased  as  part  of  the  backup  operation  (unless  the  /A  switch  is  included 
in  the  command  line  and  the  destination  disk  has  already  been  used  as  a  backup  disk — 
that  is,  the  \BACKUP  directory  contains  a  valid  BACKUPID.@@@  file).  Other  files  on  the 
destination  fixed  disk  are  not  disturbed. 

A  control  file  named  BACKUPID.@@@  is  placed  on  every  floppy  disk  onto  which  files  are 
backed  up  or  in  the  /BACKUP  directory  if  the  files  are  backed  up  onto  a  fixed  disk.  The 
BACKUPID.@@@  file  has  the  following  format: 


Byte 

Value 

Use 

OOH 

OOorFFH 

Not  last  floppy  disk/last  floppy  disk 

01-02H 

nn 

Floppy  disk  number  in  low-byte/high-byte  decimal  format 

03-04H 

nnnn 

Full  year  in  low-byte/high-byte  order 

05H 

1-31 

Day  of  the  month 

06H 

1-12 

Month  of  the  year 

07-0AH 

nnnn 

Standard  MS-DOS  system  time  if  the  /I -.time  switch  was  used; 

Otherwise  0 

0B-7FH 

00 

Not  used 

Each  backed-up  file  also  has  a  128-byte  header  added  to  it  when  it  is  created.  The  header 
has  the  following  format: 

Byte 

Value 

Use 

OOH 

OOorFFH 

Not  last  floppy  disk/last  floppy  disk  on  which  this  file  resides 

OlH 

nn 

Floppy  disk  number 

02-04H 

00 

Not  used 

(more) 
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Byte 

Value 

Use 

05-44H 

nn 

File’s  full  pathname,  except  for  drive  designator 

45-52H 

00 

Not  used 

53H 

nn 

Length  of  the  file’s  pathname  plus  one 

54-7FH 

00 

Not  used 

The  /T\time,  /T>:date,  and  /M  switches  allow  incremental  or  partial  backups.  The  /T:time 
switch  excludes  files  modified  or  created  before  a  certain  time  and  should  be  used  in  the 
form  of  the  COUNTRY  command  in  effect  For  the  USA,  the  format  is  /T:  hh.mm.ss,  (The 
/^\time  switch  is  not  supported  in  all  implementations  of  BACKUP.)  The  /T>:date switch 
excludes  files  modified  or  created  before  a  certain  date  and  should  be  used  in  the  form 
of  the  COUNTRY  command  in  effect.  For  the  USA,  the  format  is  /D:  mm-dd-yy.  The  /M 
switch  selects  only  those  files  that  have  been  modified  since  the  last  backup  operation. 

The  /L:  filename  switch  causes  a  log  file  to  be  created  on  the  source  disk.  This  file 
includes  the  name  of  each  file  backed  up,  the  time  and  date,  and  the  number  of  the  des¬ 
tination  disk  that  received  that  backup  file.  If  filename  is  omitted,  the  name  defaults  to 
BACKUP.LOG.  Use  of  the  /L:  filename  switch  can  cause  compatibility  problems  between 
MS-DOS  and  PC-DOS  because  the  backup  log  file  may  match  the  search  pattern  and  be 
backed  up,  too,  resulting  in  an  extra  file  on  the  backup  disk. 

The  /P  switch  causes  backup  files  to  be  packed  as  densely  as  possible  on  the  destination 
disk.  When  many  short  files  are  being  backed  up  to  floppy  disks,  the  number  of  files  that 
fit  on  the  destination  disk  may  exceed  the  number  of  entries  that  will  fit  in  the  destina¬ 
tion’s  root  directory.  If  the  /P  switch  is  included  in  the  command  line,  subdirectories  are 
created  on  the  destination  disk  as  needed  to  use  the  disk  space  more  effectively.  The  /P 
switch  is  not  supported  under  PC-DOS;  backup  disks  created  with  the  /P  switch  will  not 
be  compatible  with  IBM’s  BACKUP  and  RESTORE  commands. 

Warning:  BACKUP  should  not  be  used  on  disk  directories  or  drives  that  have  been 
redirected  with  an  ASSIGN,  JOIN,  or  SUBST  command. 

Return  Codes 

0  Backup  operation  was  successful. 

1  No  files  were  found  to  back  up. 

2  Some  files  were  not  backed  up  because  of  sharing  conflicts  (versions  3.0  and  later). 

3  Backup  operation  was  terminated  by  user. 

4  Backup  operation  was  terminated  because  of  error. 

Examples 

To  back  up  the  file  REPORT.TXT  in  the  current  directory  on  the  current  drive,  placing  the 
backup  file  on  the  disk  in  drive  A,  type 

OBACKUP  REPORT.TXT  A:  <Enter> 
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To  back  up  all  the  files  in  the  subdirectory  B:\V2\SOURCE,  placing  the  backup  files  on  the 
disk  in  drive  A,  type 

OBACKUP  B:\V2\S0URCE  A:  <Enter> 

To  back  up  all  the  files  with  extension  .C  in  the  directory  \V2\ SOURCE  on  the  current 
drive,  placing  the  backup  files  on  the  disk  in  drive  A,  type 

OBACKUP  \V2\S0URCE\*  .C  A:  <Enter> 

To  back  up  all  the  files  with  the  extension  .ASM  from  the  current  directory  on  the  current 
drive  and  from  all  its  subdirectories,  placing  the  backup  files  on  the  disk  in  drive  A,  type 

OBACKUP  *.ASM  A:  /S  <Enter> 

To  back  up  all  the  files  that  have  been  modified  since  the  last  backup  from  all  the  sub¬ 
directories  on  drive  C,  placing  the  backup  files  on  the  disk  in  drive  A,  type 

OBACKUP  C:\  A:  /S  /M  <Enter> 

To  back  up  all  the  files  with  the  extension  .C  from  the  directory  C:\V2\SOURCE  that  were 
modified  on  or  after  October  l6, 1985,  placing  the  backup  files  on  the  disk  in  drive  A,  type 

OBACKUP  C:\V2\S0URCE\*  .C  A:  /D:  10-1  6-85  <Enter> 

Messages 

♦♦♦Backing  up  files  to  drived:  ♦♦♦ 

Diskette  Number:  n 

This  informational  message  informs  the  user  of  the  progress  of  the  BACKUP  command. 

♦♦♦Last  file  not  backed  up  ♦♦♦ 

The  destination  drive  does  not  have  enough  space  to  back  up  the  last  file. 

♦♦♦Not  able  to  back  up  file  ♦♦♦ 

One  of  the  system  calls  used  by  BACKUP  failed  unexpectedly;  for  example,  a  file  could  not 
be  opened,  read,  or  written. 

Cannot  create  Subdirectory  BACKUP  on  drived: 

Drive  X  is  full  or  its  root  directory  is  full. 

DOS  2.0  or  later  required 

BACKUP  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Error  trying  to  open  backup  log  file 
Continuing  without  making  log  entries 

The  /L  switch  was  used  and  BACKUP  is  unable  to  create  the  backup  log  file. 


% 
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Files  cannot  be  added  to  this  diskette 
unless  the  PACK  (/P)  switch  is  used 
Set  the  switch  (Y/N)? 

The  root  directory  of  the  destination  disk  is  full  and  a  subdirectory  must  be  created  to  hold 
the  remaining  files.  Respond  with  V  to  cause  BACKUP  to  create  a  subdirectory  and  con¬ 
tinue  backing  up  files  into  it;  respond  with  N  to  return  to  MS-DOS. 

Incorrect  DOS  version 

The  version  of  BACKUP  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insert  backup  diskette  in  drive  Y: 

Strike  any  key  when  ready 

This  message  prompts  the  user  to  insert  a  disk  to  receive  the  backup  files  into  the  speci¬ 
fied  destination  drive. 

Insert  backup  diskette  it  in  drive  Y: 

Strike  any  key  when  ready 

The  files  being  backed  up  will  not  fit  onto  a  single  floppy  disk;  this  message  prompts  the 
user  to  insert  the  next  floppy  disk.  Multiple-floppy-disk  backup  disks  should  be  labeled 
and  numbered  to  match  the  number  displayed  in  this  message. 

Insert  backup  source  diskette  in  drive  Y: 

Strike  any  key  when  ready 

This  message  prompts  the  user  to  insert  the  floppy  disk  to  be  backed  up  into  the  specified 
source  drive. 

Insert  last  backup  diskette  in  drive  Y: 

Strike  any  key  when  ready 

This  message  prompts  the  user  to  insert  the  final  disk  that  will  receive  the  backup  files 
into  the  specified  destination  drive. 

Insufficient  memory 

Available  system  memory  is  insufficient  to  run  the  BACKUP  program. 

Invalid  argument 

One  of  the  switches  specified  in  the  command  line  is  invalid  or  is  not  supported  in  the  ver¬ 
sion  of  BACKUP  being  used. 

Invalid  Date/Time 

An  invalid  date  or  time  was  given  with  the  /T>:date  or  /T.time  switch. 

Invalid  drive  specification 

The  source  or  destination  drive  specified  in  the  command  line  is  not  available  or  is  not 
valid. 

Invalid  number  of  parameters 

At  least  two  parameters,  the  source  and  the  destination,  must  be  specified  in  the  com¬ 
mand  line;  a  maximum  of  seven  switches  can  be  specified  after  the  source  and 
destination. 
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Invalid  parameter 

One  of  the  switches  supplied  in  the  command  line  is  invalid. 

Invalid  path 

The  path  specified  as  the  source  is  invalid  or  does  not  exist. 

Last  backup  diskette  not  inserted 
Insert  last  backup  diskette  in  drive  Jf: 

Strike  any  key  when  ready 

The  backup  disk  inserted  as  the  last  backup  disk  was  not  the  correct  disk.  Insert  the  cor¬ 
rect  disk. 

No  space  left  on  device 

The  destination  disk  is  full. 

No  such  file  or  directory 

The  source  specified  is  invalid  or  does  not  exist. 

Source  and  target  drives  are  the  same 

The  disks  specified  as  the  source  and  destination  disks  are  identical. 

Source  disk  is  Non-removable 

The  disk  containing  the  files  to  be  backed  up  is  a  fixed  disk. 

Target  can  not  be  used  for  backup 

The  disk  specified  as  the  destination  disk  is  damaged  or  the  /A  switch  was  used  in  the 
command  line  and  the  disk  does  not  contain  a  valid  BACKUPID.@@@  file. 

Target  disk  is  Non-removable 

The  disk  that  will  contain  the  backed-up  files  is  a  fixed  disk. 

Target  is  a  floppy  disk 

or 

Target  is  a  hard  disk 

This  informational  message  indicates  which  type  of  disk  was  specified  as  the  destination 
disk. 

Too  many  open  files 

Too  many  files  are  open.  Increase  the  value  of  the  FILES  command  in  the  CONFIG.SYS 
file. 

Unable  to  erase  filename 

BACKUP  is  unable  to  erase  an  older  version  of  a  backed-up  file  because  the  file  is  read¬ 
only  or  is  in  use  by  another  program. 
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Warning!  Files  in  the  target  drive 
X:  \  root  directory  will  be  erased 
Strike  any  key  when  ready 

The  destination  is  a  floppy-disk  drive  and  this  message  warns  the  user  that  all  files  in  its 
root  directory  will  be  erased  before  the  backup  operation. 

Warning!  Files  in  the  target  drive 
C:\BACKIJP  directory  will  be  erased 
Strike  any  key  when  ready 

BACKUP  is  ready  to  begin  backing  up  files  to  the  \BACKUP  directory  on  drive  C.  All  exist¬ 
ing  files  in  the  \BACKUP  directory  will  be  deleted.  Press  Crtl-Break  to  terminate  the 
backup  operation  or  press  any  key  to  continue. 

Warning!  No  files  were  found  to  back  up 

No  files  were  found  on  the  source  disk  in  the  current  or  specified  directory  or  no  files  were 
found  matching  the  filename  supplied. 
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BATCH  1.0  and  later 

System  Batch-File  Interpreter  Internal 

Purpose 

Sequentially  executes  commands  stored  in  a  batch  file  (a  text-only  file  with  a  .BAT 
extension). 

Syntax 

filename  [[parameterl  [parameter2  [...]]]] 
where: 

filename  is  the  name  of  the  batch  file  to  be  executed,  without  the  .BAT  extension. 

(The  filename  is  always  %0  in  the  list  of  replaceable  parameters.) 
parameterl  is  the  filename,  switch,  or  string  that  is  the  value  of  the  first  replaceable 
parameter  (%1). 

parameter2  is  the  filename,  switch,  or  string  that  is  the  value  of  the  second  replaceable 
parameter  (%2).  As  many  additional  replaceable  parameters  can  be  speci¬ 
fied  as  the  command  line  will  hold. 

Description 

A  batch  file  is  an  ASCII  text  file  that  contains  one  or  more  MS-DOS  commands.  It  is  a  use¬ 
ful  way  to  perform  sequences  of  frequently  used  commands  without  having  to  type  them 
all  each  time  they  are  needed.  When  a  batch  file  is  invoked  by  entering  its  name,  the  com¬ 
mands  it  contains  are  carried  out  in  sequence  by  a  special  batch-file  interpreter  built  into 
COMMAND.COM.  Additional  information  entered  in  the  batch-file  command  line  can  be 
passed  to  other  programs  by  means  of  replaceable  parameters  {see  belovu). 

A  batch  file  must  always  have  the  extension  .BAT.  The  file  can  contain  any  number  of  lines 
of  ASCII  text;  each  line  can  contain  a  maximum  of  128  characters.  Batch  files  can  be  cre¬ 
ated  with  EDLIN  or  another  text  editor  or  with  a  word  processor  in  nondocument  mode. 
(Formatted  document  files  cannot  be  used  as  batch  files  because  they  contain  special  con¬ 
trol  codes  or  escape  sequences  that  cannot  be  processed  by  the  batch-file  interpreter.) 
Batch  files  can  also  be  created  with  the  MS-DOS  COPY  command  by  specifying  the  CON 
device  (keyboard)  as  the  source  file  and  the  desired  batch-file  name  as  the  destination  file. 
For  example,  after  the  command 

C>COPY  CON  MYFILE.BAT  <Enter> 

each  line  that  is  typed  will  be  placed  into  MYFILE.BAT.  This  form  of  the  COPY  command 
is  terminated  by  pressing  Ctrl-2  or  the  F6  key,  followed  by  the  Enter  key. 

The  commands  in  a  batch  file  can  be  any  combination  of  internal  MS-DOS  commands 
(such  as  DIR  or  COPY),  external  MS-DOS  commands  (such  as  CHKDSK  or  BACKUP),  the 
names  of  other  programs  or  batch  files,  or  the  following  special  batch-file  directives: 


752  The  MS-DOS  Encyclopedia 


BATCH 


Command  Action 

ECHO  Displays  a  message  on  standard  output  (versions  2.0  and  later). 

FOR  Executes  a  command  on  each  of  a  set  of  files  (versions  2.0  and 

later). 

GOTO  Transfers  control  to  another  point  in  a  batch  file  (versions  2.0 

and  later). 

IF  Conditionally  executes  a  command  based  on  the  existence  of  a 

file,  the  equality  of  two  strings,  or  the  return  code  of  a  previously 
run  program  (versions  2.0  and  later). 

PAUSE  Waits  for  the  user  to  press  a  key  before  executing  the  remainder  of 

the  batch  file. 

REM  Allows  comment  lines  to  be  placed  in  batch  files  for  internal 

documentation. 

SHIFT  Provides  access  to  more  than  10  command-line  parameters  (ver¬ 

sions  2.0  and  later). 


These  special  batch  commands  are  discussed  individually,  with  examples,  in  the  following 
pages. 

A  batch  file  is  executed  by  entering  its  name,  without  the  .BAT  extension,  in  response  to 
the  MS-DOS  prompt.  The  system’s  command  processor,  COMMAND.COM,  searches  the 
current  directory  and  then  each  directory  named  in  the  PATH  environment  variable  for  a 
file  with  the  specified  name  and  the  extension  .COM,  .EXE,  or  .BAT,  in  that  order.  If  a 
.COM  or  .EXE  file  is  found,  it  is  loaded  into  memory  and  receives  control;  if  a  .BAT  file  is 
found,  it  is  assumed  to  be  a  text  file  and  is  passed  to  the  batch-file  interpreter.  (If  two  files 
with  the  same  name  exist  in  the  samq  directory,  one  with  a  .COM  or  .EXE  extension  and 
the  other  with  a  .BAT  extension,  it  is  not  possible  to  execute  the  .BAT  file — the  .COM  or 
.EXE  file  is  always  loaded  instead.) 


If  the  disk  that  contains  a  batch  file  is  removed  before  all  the  commands  in  the  batch  file 
are  executed,  COMMAND.COM  will  prompt  the  user  to  replace  the  disk  so  that  the  batch 
file  can  be  completed.  Execution  of  a  batch  file  can  be  terminated  by  pressing  Ctrl-C  or 
Ctrl-Break,  causing  COMMAND.COM  to  issue  the  message  Terminate  batch  job?  (Y/N).  If 
the  user  responds  with  Y,  the  batch  file  is  abandoned  and  COMMAND.COM  displays  its 
usual  prompt. 

The  input  redirection  (<),  output  redirection  (>  or  »),  and  piping  (1)  characters  have  no 
effect  when  they  are  used  in  a  command  line  that  invokes  a  batch  file.  However,  they  can 
be  used  in  individual  command  lines  within  the  file. 


Ordinarily,  if  a  batch  file  includes  the  name  of  another  batch  file,  control  passes  to  the  sec¬ 
ond  batch  file  and  never  returns.  That  is,  when  the  commands  in  the  second  batch  file  are 
completed,  the  batch-file  interpreter  terminates  and  any  remaining  commands  in  the  first 
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batch  file  are  not  processed.  However,  a  batch  file  can  execute  another  batch  file  without 
itself  being  terminated  by  first  loading  a  secondary  copy  of  the  system’s  command  pro¬ 
cessor.  To  accomplish  this,  the  first  batch  file  must  contain  a  command  of  the  form 

COMMAND  /G  batch2 

where  batch2  is  the  name  of  the  second  batch  file.  When  all  the  commands  in  the  second 
batch  file  have  been  processed,  the  secondary  copy  of  COMMAND.COM  exits  and  the 
first  batch  file  continues  where  it  left  off.  iSee  USER  COMMANDS:  command  for  details  on 
the  use  of  the  /C  switch  with  COMMAND.COM.) 

A  batch  file  can  be  made  more  flexible  by  including  replaceable  parameters  inside  the  file. 
A  replaceable  parameter  takes  the  form  96n,  where  w  is  a  numeral  in  the  range  0  through  9. 
Replaceable  parameters  simply  hold  places  in  the  batch  file  for  filenames  or  other  informa¬ 
tion  that  the  user  will  supply  in  the  command  line  when  the  batch  file  is  invoked. 

When  a  batch  file  is  interpreted  and  a  command  containing  a  replaceable  parameter  is 
encountered,  the  corresponding  value  specified  in  the  batch-file  command  line  is  substi¬ 
tuted  for  the  replaceable  parameter  and  the  command  is  then  executed.  The  %0  replace¬ 
able  parameter  is  replaced  by  the  name  of  the  batch  file  itself;  parameters  %1  through  %9 
are  replaced  sequentially  with  the  remaining  values  specified  in  the  command  line.  If  a 
replaceable  parameter  references  a  command-line  entry  that  does  not  exist,  the  parameter 
is  replaced  with  a  null  (zero-length)  string. 

For  example,  if  the  batch  file  MYBATCH.BAT  contains  the  single  line 

COPY  %1.C0M  %2.SAV 

and  is  executed  by  entry  of 

OmYBATCH  FILEI  FILE2  <Enter> 

the  actual  command  that  is  carried  out  is 

COPY  FILE1.COM  FILE2.SAV 

(The  SHIFT  batch  command  makes  it  possible  to  use  more  than  10  replaceable  parame¬ 
ters.  See  USER  COMMANDS:  batch:shift) 

An  environment  variable  is  a  special  case  of  a  replaceable  parameter.  If  the  SET  command 
is  used  in  the  form 

SET  name^value 

to  add  an  environment  variable  to  the  system’s  environment  block,  the  string  value  will  be 
substituted  for  the  string  %name%  wherever  the  latter  is  encountered  during  the  inter¬ 
pretation  of  a  batch  file.  This  capability  is  available  only  in  versions  2.x,  3.1,  and  3.2. 
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BATCH:  AUTOEXEC^T  1.0  and  later 

System  Startup  Batch  File 


Description 

The  AUTOEXEC.BAT  file  is  an  optional  batch  file  containing  a  series  of  MS-DOS  com¬ 
mands  that  automatically  execute  when  the  system  is  turned  on  or  restarted. 

When  the  system’s  default  command  processor,  COMMAND.COM,  is  first  loaded,  it 
looks  in  the  root  directory  of  the  current  drive  for  a  file  named  AUTOEXEC.BAT.  If 
AUTOEXEC.BAT  is  not  found,  COMMAND.COM  prompts  the  user  to  enter  the  current 
time  and  date  and  then  displays  the  MS-DOS  copyright  notice  and  command  prompt.  If 
AUTOEXEC.BAT  is  found,  COMMAND.COM  sequentially  executes  the  commands  within 
the  file.  No  prompts  to  enter  the  time  and  date  are  issued  unless  the  TIME  and  DATE 
commands  are  explicitly  included  in  the  batch  file;  no  copyright  notice  is  displayed. 

Typical  uses  of  the  AUTOEXEC.BAT  file  include 

•  Running  a  program  to  set  the  system  time  and  date  from  a  real-time  clock/calendar 
located  on  a  multipurpose  expansion  board  (IBM  PC,  PC/XT,  or  compatibles  only) 

•  Using  the  MODE  command  to  configure  a  serial  port  or  to  redirect  printing 

•  Executing  SET  commands  to  configure  environment  variables 

•  Setting  display  colors  on  a  color  monitor  (if  the  command  DEVICE=ANSLSYSh2iS 
been  included  in  the  CONFIG.SYS  file) 

•  Installing  terminate-and-stay-resident  (TSR)  utilities 

•  Using  the  PATH  command  to  tell  COMMAND.COM  where  to  find  executable  pro¬ 
gram  files  if  they  are  not  in  the  current  drive  and/or  directory 

•  Defining  a  custom  prompt  using  the  PROMPT  command 

•  Invoking  an  application  program  such  as  a  database,  spreadsheet,  or  word  processor 

A  secondary  copy  of  the  command  processor  can  also  be  loaded  from  within  the 
AUTOEXEC.BAT  file.  If  this  copy  of  COMMAND.COM  is  loaded  with  the  /P  switch,  it  too 
searches  for  an  AUTOEXEC.BAT  file  on  the  current  drive  and  processes  the  file  if  it  is 
found.  This  feature  can  be  useful  for  performing  special  operations.  For  example,  on  very 
old  PCs  that  are  unable  to  start  from  a  fixed  disk,  a  secondary  copy  of  the  command  pro¬ 
cessor  can  be  used  to  make  the  fixed  disk’s  copy  of  COMMAND.COM  the  copy  used  by 
the  system  from  that  point  on  (at  the  expense  of  some  system  memory).  If  the 
AUTOEXEC.BAT  file  containing  the  lines 


C: 

COMMAND  C:\  /P 

is  stored  on  the  floppy  disk  in  drive  A  when  the  system  is  turned  on  or  restarted,  the 
first  line  of  the  file  causes  drive  C  to  become  the  current  drive;  then  the  second  line 
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permanently  loads  a  secondary  copy  of  COMMAND.COM  from  drive  C  and  instructs 
COMMAND.COM  to  reload  its  transient  portion  from  the  root  directory  of  drive  C  when 
necessary.  This  in  turn  triggers  the  execution  of  the  AUTOEXEC.BAT  file  on  the  fixed 
disk  to  perform  the  actual  system  configuration.  Because  the  transient  part  of 
COMMAND.COM  will  be  reloaded  from  the  fixed  disk  when  necessary,  rather  than 
from  the  floppy  disk,  system  performance  is  improved  considerably. 

Example 

The  following  example  illustrates  several  common  uses  of  the  AUTOEXEC.BAT  file  to  con¬ 
figure  the  MS-DOS  system  at  startup  time.  (The  line  numbers  are  included  for  reference 
and  are  not  part  of  the  actual  file.) 

1  ECHO  OFF 

2  SETCLOCK 

3  PROMPT  $p$g 

4  MD  D:\BIN 

5  COPY  C:\SYSTEM\*.*  D:\BIN  >  NUL 

6  PATH=D : \BIN; C : \WP\WORD; C : \MSC\BIN; C : \ASM 

7  APPEND  D:\BIN; C:\WP\WORD; C:\ASM 

8  SET  INCLUDE=C:\MSC\ INCLUDE 

9  SET  LIB=C:\MSC\LIB 

10  SET  TMP=C;\TEMP 

11  MODE  C0M1 : 9600,n, 8, 1 ,p 

12  MODE  LPT1:=C0M1: 

Line  1  causes  the  batch-file  processor  to  operate  silently;  that  is,  the  commands  in  the 
batch  file  are  not  displayed  on  the  screen  as  they  are  executed. 

Line  2  runs  a  utility  program  called  SETCLOCK,  which  reads  the  current  time  and  date 
from  a  real-time  clock  chip  on  a  multifunction  board  and  sets  the  system  time  and  date 
accordingly. 

Line  3  configures  COMMAND.COM’s  user  prompt  so  that  it  displays  the  current  drive  and 
directory. 

Line  4  creates  a  directory  named  \BIN  on  drive  D,  which  in  this  case  is  a  RAMdisk  that 
was  created  by  an  entry  in  the  system's  CONFIG.SYS  file. 

Line  5  copies  all  the  programs  in  the  \  SYSTEM  directory  on  drive  C  to  the  \BIN  directory 
on  drive  D.  The  normal  output  of  this  COPY  command  is  redirected  to  the  NUL  device — 
in  effect,  the  output  is  thrown  away — to  avoid  cluttering  the  screen. 

Line  6  sets  the  search  path  for  executable  files  and  line  7  sets  the  search  path  for  data  files. 
Note  that  the  RAMdisk  directory  D:\BIN  is  specified  as  the  first  directory  in  the  PATH 
command;  therefore,  if  the  name  of  a  program  is  entered  and  it  cannot  be  found  in  the  cur¬ 
rent  directory,  COMMAND.COM  will  look  next  in  the  directory  D:\BIN.  This  strategy 
allows  commonly  used  programs  (in  this  example,  the  programs  in  the  \  SYSTEM  direc¬ 
tory  that  were  copied  into  D:\BIN)  to  be  located  and  loaded  quickly. 
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Lines  8  through  10  add  the  environment  variables  INCLUDE,  LIB,  and  TMP  to  the  system’s 
environment.  These  variables  are  used  by  the  Microsoft  C  Compiler  and  the  Microsoft 
Object  Linker. 

Line  11  configures  the  first  serial  communications  port  (COMl)  and  line  12  causes  program 
output  to  the  system’s  first  parallel  port  (LPTl)  to  be  redirected  to  the  first  serial  port.  This 
pair  of  commands  allows  a  serial-interface  Hewlett  Packard  LaserJet  printer  to  be  used  as 
the  system  list  device. 

Note:  Depending  on  the  version  of  MS-DOS  in  use,  some  commands  in  this  example  may 
not  be  available  or  may  support  different  options.  See  the  individual  command  entries  for 
more  detailed  information. 
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BATCH:  ECHO 

Display  Text 


2.0  and  later 
Internal 


Purpose 

Displays  a  message  during  the  execution  of  a  batch  file  and  controls  whether  or  not  batch- 
file  commands  are  listed  on  the  screen  as  they  are  executed. 

Syntax 

ECHO  [ON  1  OFF  1  message] 
where: 

ON  enables  the  display  of  all  subsequent  batch-file  commands  as  they  are 

executed. 

OFF  disables  the  display  of  all  subsequent  batch-file  commands  as  they  are 
executed. 

message  is  a  text  string  to  be  displayed  on  standard  output. 

Description 

Each  command  line  of  a  batch  file  is  ordinarily  displayed  on  the  screen  as  it  is  executed. 
The  ECHO  command  has  a  dual  usage:  to  control  the  display  of  these  commands  and  to 
display  a  message  to  the  user. 

ECHO  is  used  with  ON  or  OFF  to  enable  or  disable  the  display  of  commands  during 
batch-file  processing.  If  the  ECHO  command  is  used  with  no  parameter,  the  current  status 
of  the  batch  processor’s  ECHO  flag  is  displayed.  Note  that  the  ECHO  flag  is  always  forced 
on  at  the  start  of  any  batch-file  processing,  even  if  that  batch  file  was  invoked  by  another 
batch  file. 

The  ECHO  command  is  not  limited  to  batch  files;  an  ECHO  command  can  also  be  issued 
at  the  command  prompt.  ECHO  OFF  entered  at  the  command  prompt  prevents  the 
prompt  from  subsequently  being  displayed.  ECHO  ON  entered  interactively  restores  the 
display.  If  ECHO  is  entered  interactively  without  a  parameter,  the  current  status  of  the 
ECHO  flag  is  displayed. 

ECHO  can  also  be  followed  by  a  message  to  be  sent  to  standard  output  regardless  of  the 
status  of  the  ECHO  flag  (on  or  off).  Note  that  if  ECHO  is  on,  two  copies  of  the  message 
are  actually  displayed,  the  first  copy  preceded  by  the  word  ECHO.  ECHO  message  is  fre¬ 
quently  used  to  display  prompts  and  informative  text  during  the  execution  of  a  batch  file 
because  text  following  REM  or  PAUSE  commands  is  not  displayed  if  ECHO  is  off. 

ECHO  message  can  also  be  used  to  build  lists  or  other  batch  files  dynamically  while  the 
batch  file  is  executing.  For  example,  the  messages  in  the  following  ECHO  commands  are 
used  to  build  the  file  STARTUP.BAT: 

ECHO  CHKDSK  >  STARTUP.BAT 
ECHO  DIR  /W  »  STARTUP.BAT 
ECHO  PROMPT  $p$g  »  STARTUP.BAT 
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The  first  ECHO  command  causes  the  message  CHKDSK  to  be  redirected  to  the  file 
STARTUP.BAT.  The  second  and  third  ECHO  commands  cause  the  messages  DIR/W  and 
PROMPT  $p$g  to  be  appended  to  the  existing  contents  of  STARTUP.BAT.  The  completed 
STARTUP.BAT  file  contains  the  following: 

CHKDSK 
DIR  /W 
PROMPT  $p$g 

Note:  When  the  pipe  symbol  (!)  is  used  in  message,  the  symbol  and  any  characters  follow¬ 
ing  it  are  ignored  until  a  redirection  symbol  (<,  >,  or  »)  is  encountered,  at  which  point  the 
redirection  symbol  and  the  remaining  characters  are  recognized.  For  example,  if  the  line 

ECHO  DIR  !  SORT  >  STARTUP.BAT 

was  placed  in  a  batch  file  and  subsequently  executed,  the  only  characters  echoed  to  the 
file  STARTUP.BAT  would  be  DIR\  the  pipe  symbol  and  the  characters  between  it  and  the 
redirection  symbol  >  would  be  ignored. 

Examples 

To  disable  the  display  of  each  batch-file  command  as  it  is  executed,  include  the  following 
line  as  the  first  line  in  the  batch  file: 

ECHO  OFF 

To  display  the  message  Now formatting  disk  on  standard  output,  include  the  following 
line  in  the  batch  file: 

ECHO  Now  formatting  disk 

To  display  the  current  status  of  the  ECHO  flag,  include  the  following  line  in  the  batch  file: 

ECHO 

If  the  ECHO  flag  is  currently  off,  MS-DOS  displays: 

ECHO  is  off 

To  echo  a  blank  line  to  the  screen  with  versions  2.x,  type  a  space  after  the  ECHO  com¬ 
mand  and  press  Enter.  To  echo  a  blank  line  with  versions  3.x,  type  the  ECHO  command 
and  a  space,  then  hold  down  Alt  and  type  255  on  the  numeric  keypad;  finally,  release  the 
Alt  key  and  press  Enter. 

Messages 

ECHO  is  off 

or 

ECHO  is  on 

If  the  ECHO  command  is  entered  without  a  parameter,  one  of  these  lines  is  displayed  to 
give  the  current  status  of  the  batch  processor’s  ECHO  flag. 
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BATCH:  FOR  2.0  and  later 

Execute  Command  on  File  Set  internal 


Purpose 

Executes  a  command  or  program  for  each  file  in  a  set  of  files. 

Syntax 

FOR  %%variable  IN  isef)  DO  command  (batch  processing) 
or 

FOR  ^variable  IN  (^set)  DO  command  (interactive  processing) 
where: 
variable 


set 


command 

Description 

The  FOR  command  allows  sequential  execution  of  the  same  command  or  program  on 
each  member  of  a  set  of  files. 

The  set  parameter  can  contain  multiple  filenames  (including  wildcards),  pathnames,  char¬ 
acter  strings,  or  metacharacters  such  as  the  replaceable  parameters  %0  through  %9.  Each  of 
the  following  lines  is  an  example  of  a  valid  set: 

{FILE1.TXT  %1  %2  B:\PROG\LISTING?, TXT) 

(A:\%1  A:\%2  C : \LETTERS\* . TXT  C:MEMO?.*) 

(%PATH%) 

Each  filename  from  5^/ is  assigned  in  turn  to  %variable  and  then  the  specified  command 
or  program  is  executed.  (When  the  FOR  command  line  is  executed  in  a  batch  file,  the 
leading  percent  sign  of  %%variable  is  removed,  leaving  %variable.')  If  a  filename  in  set 
contains  wildcards,  each  matching  file  is  used  before  the  batch  processor  goes  on  to  the 
next  member  of  set. 


is  a  variable  name  that  can  be  any  single  character  except  the  numerals  0 
through  9,  the  redirection  symbols  (<,  >,  and  »),  and  the  pipe  symbol  (1); 
case  is  significant. 

is  one  or  more  filenames,  pathnames,  character  strings,  or  metacharacters, 
separated  by  spaces,  commas,  or  semicolons;  wildcard  characters  are  per¬ 
mitted  in  filenames. 

is  any  MS-DOS  command  or  program  except  the  FOR  command;  the  vari¬ 
able  name  %%variable  (or  %variable  in  interactive  mode)  can  be  part  of 
the  command. 
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Note:  In  versions  2.x,  set  can  consist  only  of  a  list  of  single  filenames,  a  single  filename 
with  wildcard  characters,  or  a  combination  of  single  filenames  and  metacharacters.  In  ver¬ 
sions  3.x,  however,  all  combinations  of  these  are  allowed  in  the  same  set. 

The  FOR  command  can  also  be  used  interactively  at  the  MS-DOS  prompt  to  perform  a 
single  command  on  several  files  without  entering  the  same  command  for  each  file.  When 
FOR  is  used  in  this  manner,  only  one  percent  sign  (%)  should  be  used  before  the  dummy 
alphabetic  variable;  in  this  case,  the  percent  sign  is  not  removed  during  processing.  When 
the  FOR  command  is  used  interactively,  environment  variables  such  as  %PATH%  cannot 
be  used  as  part  of  the  filename  set. 

Examples 

To  view  all  the  files  with  the  extension  .TXT  in  the  current  directory,  include  the  following 
line  in  the  batch  file: 

FOR  %%X  IN  (*.TXT)  DO  TYPE  %%X 

To  perform  the  same  function  interactively,  type 

OFOR  %X  IN  (*.TXT)  DO  TYPE  %X  <Enter> 

To  copy  up  to  nine  files  to  the  disk  in  drive  A,  specifying  the  names  of  the  files  in  the 
batch-file  command  line,  include  the  following  line  in  the  batch  file: 

FOR  %%Y  IN  (%1  %2  %3  %4  %5  %6  %7  %8  %9)  DO  COPY  %%Y  A: 

(Recall  that  %0  is  the  name  of  the  batch  file.) 

To  execute  successive  batch  files  under  the  control  of  one  batch  file,  use  the  /C  switch  with 
COMMAND,  as  in  the  following  batch-file  line: 

FOR  %%Z  IN  (BAT1  BAT2  BAT3)  DO  COMMAND  /C  %%Z 

Message 

FOR  cannot  be  nested 

The  command  or  program  performed  by  a  FOR  command  cannot  be  another  FOR 
command. 
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BAXCH:  GOXO  2.0  and  later 

Jump  to  Label  Internal 


Purpose 

Transfers  program  control  to  the  batch-file  line  following  the  specified  label. 

Syntax 

GOTO  name 
where: 

name  is  a  batch-file  label  declared  elsewhere  in  the  file  in  the  form  .name. 

Description 

The  GOTO  command  causes  the  batch-file  processor  to  transfer  its  point  of  execution  to 
the  line  following  the  specified  label.  If  the  label  does  not  exist  in  the  file,  execution  of  the 
batch  file  is  terminated  with  the  message  Label  not  found. 

A  batch-file  label  is  defined  as  a  line  with  a  colon  character  (:)  in  the  first  column,  followed 
by  any  text  (including  spaces  but  not  other  separator  characters  such  as  semicolons  or 
equal  signs).  Only  the  first  eight  characters  following  the  colon  are  significant;  spaces  are 
not  counted  in  the  eight  characters. 

Examples 

The  GOTO  command  is  frequently  used  in  combination  with  the  IF  and  SHIFT  batch 
commands  to  perform  some  action  based  on  the  return  code  from  a  program.  For  exam¬ 
ple,  the  following  batch  file  will  back  up  a  variable  number  of  files  or  directories,  whose 
names  are  specified  in  the  batch-file  command  line,  to  a  floppy  disk  in  drive  A.  The  batch 
file  accomplishes  this  by  executing  the  BACKUP  program  with  successive  pathnames 
specified  in  the  command  line  until  BACKUP  returns  a  nonzero  (error)  code.  Control  is 
then  transferred  to  the  label  :DONE,  and  the  batch  file  is  terminated. 

^  ECHO  OFF 

2  : START 

3  BACKUP  %1  A: 

4  IF  ERRORLEVEL  1  GOTO  DONE 

5  SHIFT 

6  GOTO  START 

7  : DONE 

Note  that  the  batch  file  includes  two  labels, : START  2ind  :DONE,  in  lines  2  and  7,  respec¬ 
tively.  It  also  includes  two  GOTO  commands,  in  lines  4  and  6.  (The  line  numbers  in  the 
listing  above  are  included  only  for  reference  and  are  not  present  in  the  actual  batch  file.)  If 
the  condition  in  line  4  is  true  (the  BACKUP  program  returned  an  exit  code  of  1  or  higher), 
the  remainder  of  line  4  is  executed  and  program  control  passes  to  the  :DONE  label  in 
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BATCH;  GOTO 


line  7.  If  the  condition  is  false,  program  control  passes  to  line  5,  the  SHIFT  command  is 
executed,  and  program  control  goes  to  line  6,  where  the  GOTO  statement  returns  pro¬ 
gram  control  to  line  2. 

Message 

Label  not  found 

The  specified  label  does  not  exist  in  the  batch  file. 
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BATCH:  IF 


BATCH:  IF  2.0  and  later 

Perform  Conditional  Execution  Internal 

Purpose 

Tests  a  condition  and  executes  a  command  or  program  if  the  condition  is  met. 

Syntax 

IF  [NOT]  condition  command 
where: 

condition  is  one  of  the  following: 

ERRORLEVEL  number 

The  condition  is  true  if  the  exit  code  of  the  program  last  executed  by 
COMMAND.COM  was  equal  to  or  greater  than  number  Note  that  not  all 
MS-DOS  commands  return  explicit  exit  codes. 

stringl=^ =string2 

The  condition  is  true  if  stringl  and  string2^Te  identical  after  parameter 
substitution;  case  is  significant.  The  strings  cannot  contain  separator  char¬ 
acters  such  as  commas,  semicolons,  equal  signs,  or  spaces. 

EXIST  pathname 

The  condition  is  true  if  the  specified  file  exists.  The  pathname  can  include 
metacharacters. 

command  is  the  command  or  program  to  be  executed  if  the  condition  is  true. 

Description 

The  IF  command  provides  conditional  execution  of  a  command  or  program  in  a  batch  file. 
When  condition  is  true,  IF  executes  the  specified  command,  which  can  be  another  IF 
command,  any  other  MS-DOS  internal  command,  or  a  program.  When  condition  is  not 
true,  MS-DOS  ignores  command  and  proceeds  to  the  next  line  in  the  batch  file.  The  sense 
of  any  condition  can  be  reversed  by  preceding  the  test  or  expression  with  NOT. 

Examples 

To  branch  to  the  label  :ERROR  if  the  file  LEDGER.DAT  does  not  exist,  include  the  follow¬ 
ing  line  in  the  batch  file: 

IF  NOT  EXIST  LEDGER.DAT  GOTO  ERROR 
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To  branch  to  the  label  :ONEPAR  if  the  batch-file  command  line  does  not  contain  at  least 
two  parameters,  include  the  following  line  in  the  batch  file: 

IF  ”%2 GOTO  ONEPAR 

or 

IF  %2~==~  GOTO  ONEPAR 

Note  that  the  existence  of  a  replaceable  parameter  can  be  determined  by  concatenating  it 
to  another  string.  In  the  first  example,  quotation  marks  are  concatenated  on  either  side  of 
the  replaceable  parameter;  if  %2  doesn't  exist,  "%2"==  ""  evaluates  to  ""==  which  is  true 
and  will  allow  GOTO  ONEPAR  to  be  executed.  In  the  second  example,  a  tilde  character  is 
concatenated  to  the  end  of  the  replaceable  parameter;  if  %2  doesn’t  exist,  the  argument 
becomes  ~==~. 

To  copy  the  file  specified  by  the  first  replaceable  batch-file  parameter  to  drive  A  only  if  it 
does  not  already  exist  on  the  disk  in  drive  A,  include  the  following  line  in  the  batch  file: 

IF  NOT  EXIST  A:%1  COPY  %1  A: 

To  branch  to  the  label  :DONE  if  the  first  replaceable  batch-file  parameter  exists  in  the 
\PROG  directory  on  drive  C  and  in  the  \BACKUP  directory  on  drive  C,  include  the  follow¬ 
ing  line  in  the  batch  file: 

IF  EXIST  C;\PR0G\%1  IF  EXIST  C:\BACKUP\%1.G0T0  DONE 

Messages 

Bad  command  or  filename 

The  command  following  the  condition  in  the  IF  statement  was  misspelled,  does  not  exist, 
or  was  represented  by  a  replaceable  parameter  that  was  not  supplied  in  the  command  line 
that  invoked  the  batch  file. 

Syntax  error 

The  condition  specified  in  the  IF  statement  cannot  be  tested. 
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BATCH:  PAUSE 


1.0  and  later 


Suspend  Batch-File  Execution 


Internal 


Purpose 

Displays  a  message,  suspends  execution  of  a  batch  file,  and  waits  for  the  user  to  press  a 
key. 

Syntax 

PAUSE  [message] 
where: 

message  is  a  text  string  to  be  displayed  on  standard  output. 

Description 

The  PAUSE  command  displays  the  message  Strike  a  key  when  ready. . .  and  suspends 
execution  of  a  batch  file  until  the  user  presses  a  key.  This  command  can  be  used  to  allow 
time  for  the  operator  to  change  disks,  change  the  type  of  forms  on  the  printer,  or  take 
some  other  action  that  is  necessary  before  the  batch  file  can  continue. 

If  the  batch  processor’s  ECHO  flag  is  on  when  the  PAUSE  command  is  executed,  the  entire 
line  containing  the  PAUSE  statement  is  displayed  on  the  screen  so  that  the  optional  mes¬ 
sage  is  visible  to  the  user.  The  message  Strike  a  key  when  ready. . .  is  then  displayed  on  a 
new  line  and  the  system  waits.  Note  that  Strike  a  key  when  ready. . .  is  always  displayed, 
even  if  the  ECHO  flag  is  off.  When  the  user  presses  a  key,  execution  of  the  batch  file 
resumes. 

Note:  Redirection  symbols  should  not  be  used  within  message.  They  prevent  the  message 
Strike  a  key  when  ready. . .  from  being  displayed  on  the  screen. 

If  the  user  presses  Ctrl-C  or  Ctrl-Break  while  a  PAUSE  command  is  waiting  for  a  key  to  be 
pressed,  a  prompt  is  displayed  that  gives  the  user  the  opportunity  to  terminate  the  execu¬ 
tion  of  the  batch  file.  This  same  message  is  displayed  whenever  the  user  presses  Ctrl-C  or 
Ctrl-Break  during  the  execution  of  a  batch  file;  however,  using  PAUSE  commands  supple¬ 
mented  by  appropriate  ECHO  commands  at  strategic  points  within  a  batch  file  provides 
the  user  with  clearly  defined  breakpoints  for  terminating  the  file. 

Examples 

To  display  the  message  Put  an  empty  disk  in  drive  A  and  then  wait  until  the  user  has 
pressed  a  key,  include  the  following  line  in  the  batch  file: 

PAUSE  Put  an  empty  disk  in  drive  A 
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when  this  line  of  the  batch  file  is  executed,  if  the  ECHO  flag  is  on,  the  user  sees  the  fol¬ 
lowing  messages  on  the  screen: 

OPAUSE  Put  an  empty  disk  in  drive  A 
Strike  a  key  when  ready  ,  .  . 

If  the  ECHO  flag  is  off,  only  the  message  Strike  a  key  when  ready. . .  appears. 

To  display  the  message  without  the  prompt  and  command,  the  PAUSE  command  can  be 
used  immediately  after  an  ECHO  command,  as  follows: 

ECHO  OFF 
CLS 

ECHO  Put  an  empty  disk  in  drive  A 
PAUSE 

This  batch  file  will  display  the  following  message  on  the  screen: 

Put  an  empty  disk  in  drive  A 
Strike  a  key  when  ready  .  .  . 

Note  that  the  message  must  be  included  in  an  ECHO  command.  With  ECHO  off,  a  PAUSE 
message  is  not  displayed. 
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BATCH:  REM 

Include  Comment  Line 


1.0  and  later 
Internal 


Purpose 

Designates  a  remark,  or  comment,  line  in  a  batch  file. 

Syntax 

REM  [message] 
where: 

message  is  any  text. 

Description 

The  REM  command  allows  inclusion  of  remarks,  or  comments,  within  a  batch  file. 
Remarks  are  often  used  to  document  the  purpose  of  other  commands  within  the  file  for 
the  benefit  of  those  who  may  wish  to  modify  the  file  later. 

If  the  ECHO  flag  is  on,  remarks  are  displayed  on  the  screen  during  the  execution  of  a 
batch  file.  Thus,  remarks  can  also  be  used  to  provide  information,  guidance,  or  prompts  to 
the  user;  however,  the  ECHO  and  PAUSE  commands  are  more  suitable  for  these  purposes. 

REM  can  also  be  used  alone  to  insert  blank  lines  in  a  batch  file  to  improve  readability.  (If 
ECHO  is  on,  the  word  REM  will  still  be  displayed.) 

Note:  The  redirection  symbols  (<,  >,  and  »)  and  piping  character  (1)  produce  no  mean¬ 
ingful  results  with  the  REM  command  and  should  not  be  used. 

Example 

To  document  a  batch  file’s  revision  history  with  the  internal  comment  This  batch  file  last 
modified  on  6/18/87,  include  the  following  line  in  the  batch  file: 

REM  This  batch  file  last  modified  on  6/18/87 
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BAXCH:  SHIFX  2.0  and  later 

Shift  Replaceable  Parameters  Internal 


Purpose 

Changes  the  position  of  the  replaceable  parameters  in  a  batch-file  command  line,  thereby 
allowing  more  than  10  replaceable  parameters. 

Syntax 

SHIFT 

Description 

Ordinarily  only  10  replaceable  parameters  (%0  through  %9,  where  %0  is  the  name  of  the 
batch  file)  can  be  referenced  within  a  batch  file.  The  SHIFT  command  allows  access  to  ad¬ 
ditional  parameters  specified  in  the  command  line  by  shifting  the  contents  of  each  of  the 
previously  assigned  parameters  to  a  lower  number  (%1  becomes  %0,  %2  becomes  %1,  and 
so  on).  The  previous  contents  of  %0  are  lost  and  are  not  recoverable.  The  eleventh  param¬ 
eter  in  the  batch-file  command  line  is  then  moved  into  %9.  This  allows  more  than  10 
parameters  to  be  specified  in  the  batch-file  command  line  and  subsequently  processed 
in  the  batch  file. 

Example 

The  following  batch  file  will  copy  a  variable  number  of  files,  whose  names  are  entered  in 
the  batch-file  command  line,  to  the  disk  in  drive  A: 

ECHO  OFF 
:NEXT 

IF  «%i»«==nn  goto  done 
COPY  %1  A: 

SHIFT 
GOTO  NEXT 
:DONE 
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BREAK 


BREAK 

Set  Control-C  Check 


2.0  and  later 
Internal 


Purpose 

Sets  or  clears  MS-DOS’s  internal  flag  for  Control-C  checking. 

Syntax 

BREAK  [ONIOFF] 

Description 

Pressing  Ctrl-C  or  Ctrl-Break  while  a  program  is  running  ordinarily  terminates  the  pro¬ 
gram,  unless  the  program  itself  contains  instructions  that  disable  MS-DOS’s  Control-C  han¬ 
dling.  As  a  rule,  MS-DOS  checks  the  keyboard  for  a  Control-C  only  when  a  character  is 
read  from  or  written  to  a  character  device  (keyboard,  screen,  printer,  or  auxiliary  port). 
Therefore,  if  a  program  executes  for  long  periods  without  performing  such  character  I/O, 
detection  of  the  user’s  entry  of  a  Control-C  may  be  delayed.  The  BREAK  ON  command 
causes  MS-DOS  to  also  check  the  keyboard  for  a  Control-C  at  the  time  of  each  system  call 
(which  slows  the  system  somewhat);  the  BREAK  OFF  command  disables  such  extended 
Control-C  checking.  The  default  setting  for  BREAK  is  off. 

If  the  BREAK  command  is  entered  alone,  the  current  status  of  MS-DOS’s  internal  BREAK 
flag  is  displayed. 

Examples 

To  display  the  current  status  of  the  MS-DOS  internal  flag  for  extended  Control-C  checking, 
type 

C>BREAK  <Enter> 

MS-DOS  displays 

BREAK  is  off 

or 

BREAK  is  on 

depending  on  the  status  of  the  BREAK  flag. 

To  enable  extended  checking  for  Control-C  during  disk  operations,  type 

C>BREAK  ON  <Enter> 
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Messages 

BREAKison 

or 

BREAK  is  off 

Extended  Control-C  checking  is  enabled  or  disabled,  respectively.  These  messages  occur 
in  response  to  a  BREAK  status  check. 

Must  specify  ON  or  OFF 

An  invalid  parameter  was  supplied  in  a  BREAK  command. 
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CHDIRorCD  2.0  and  later 

Change  Current  Directory  internal 


Purpose 

Changes  the  current  directory  or  displays  the  current  path  of  the  specified  or  default  disk 
drive. 

Syntax 

CHDIR  [drive{\[path] 
or 

CT>[drive‘][path\ 

where: 

drive  is  the  letter  of  the  drive  for  which  the  current  directory  will  be  changed  or 

displayed,  followed  by  a  colon.  Note  that  use  of  the  drive  parameter  does  not 
change  the  currently  active  drive. 

path  is  one  or  more  directory  names,  separated  by  backslash  characters  (\),  that 
define  an  existing  path. 

Description 

The  CHDIR  command,  when  followed  by  an  existing  path,  is  used  to  set  the  working 
directory  for  the  default  or  specified  disk  drive. 

The  path  parameter  consists  of  the  name  of  an  existing  directory,  optionally  followed  by 
the  names  of  existing  subdirectories,  each  separated  from  the  next  by  a  backslash  charac¬ 
ter.  If  path  begins  with  a'backslash,  CHDIR  assumes  that  the  first  named  directory  is  a  sub¬ 
directory  of  the  root  directory;  otherwise,  CHDIR  assumes  that  the  first  named  directory  is 
a  subdirectory  of  the  current  directory.  The  special  directory  name  •• ,  which  is  an  alias  for 
the  parent  directory  of  the  current  directory,  can  be  used  as  the  path. 

When  CHDIR  is  entered  alone  or  with  only  a  drive  letter  followed  by  a  colon,  the  full  path 
of  the  current  directory  for  the  default  or  specified  drive  is  displayed. 

CD  is  simply  an  alias  for  CHDIR;  the  two  commands  are  identical. 

Examples 

To  change  the  current  directory  for  the  current  (default)  disk  drive  to  the  path 
\V2\SOURCE,  type 

C>CD  \V2\S0URCE  <Enter> 


772  The  MS-DOS  Encyclopedia 


CHDIRorCD 


To  display  the  name  of  the  current  directory  for  the  disk  in  drive  D,  type 

C>CD  D:  <Enter> 

To  return  to  the  parent  directory  of  the  current  directory,  type 

C>CD  . .  <Enter> 

Messages 

Invalid  directory 

One  of  the  directories  in  the  specified  path  does  not  exist. 

Invalid  drive  specification 

An  invalid  drive  letter  was  given  or  the  named  drive  does  not  exist  in  the  system. 
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CHKDSK 

Check  Disk  Status 


1.0  and  later 
External 


Purpose 

Analyzes  the  allocation  of  storage  space  on  a  disk  and  displays  a  summary  report  of  the 
space  occupied  by  files  and  directories. 

Syntax 

CHKDSK  [drive'][pathname]  [/F]  [/V] 
where: 
drive 

pathname 

/F 
/V 

Description 

The  CHKDSK  command  analyzes  the  disk  directory  and  file  allocation  table  for  consis¬ 
tency  and  reports  any  errors.  If  the  /V  switch  is  included  in  the  command  line,  the  name  of 
each  file  processed  is  displayed  as  the  disk  is  being  analyzed. 

After  analyzing  the  disk,  CHKDSK  displays  a  summary  of  the  disk  and  RAM  space  used 
and  available.  The  disk-space  report  includes 

•  Total  disk  space  in  bytes 

•  Number  of  bytes  allocated  to  hidden  files 

•  Number  of  bytes  contained  in  directories 

•  Number  of  bytes  contained  in  user  files 

•  Number  of  bytes  contained  in  bad  (unusable)  sectors 

•  Number  of  available  bytes  on  the  disk 

(Hidden  files  are  files  that  do  not  appear  in  a  directory  listing.  A  bootable  MS-DOS  or 
PC-DOS  disk  always  contains  two  hidden  files — MSDOS.SYS  and  lO.SYS  or  IBMDOS.COM 
and  IBMBIO.COM,  respectively — that  contain  the  operating  system.  A  volume  label,  if 
present,  counts  as  a  hidden  file.  In  addition,  some  application  programs  create  hidden  files 
for  copy  protection  or  other  purposes.) 

Directory  errors  detected  by  CHKDSK  include 

•  Invalid  pointers  to  data  areas 

•  Bad  file  attributes  in  directory  entries 


is  the  letter  of  the  drive  containing  the  disk  to  be  analyzed,  followed  by  a 
colon. 

is  the  location  and,  optionally,  the  name  of  the  file(s)  to  be  checked  for 
fragmentation;  wildcard  characters  are  permitted  in  the  filename, 
repairs  errors  (versions  2.0  and  later). 

“verbose  mode,”  reports  the  name  of  each  file  as  it  is  checked  (versions 
2.0  and  later). 
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•  Damage  to  a  portion  of  the  directory  that  makes  it  impossible  to  check  one  or  more 
paths 

•  Damage  to  an  entire  directory  that  makes  the  files  contained  in  that  directory 
inaccessible 

File  allocation  table  (FAT)  errors  detected  by  CHKDSK  include 

•  Defective  disk  sectors  in  the  FAT 

•  Invalid  cluster  (disk  allocation  unit)  numbers  in  the  FAT 

•  Lost  clusters 

•  Cross-linking  of  files  on  the  same  cluster 


If  the  /F  switch  is  included  in  the  command  line,  CHKDSK  will  attempt  to  repair  errors  in 
disk  allocation  and  recover  as  much  data  as  possible.  Because  repairs  usually  involve 
changes  to  the  disk’s  file  allocation  table  that  may  cause  a  loss  of  information,  the  user  is 
prompted  for  confirmation.  Lost  clusters  are  collected  into  files  in  the  root  directory  with 
names  of  the  form  FILEwwww.CHK. 

If  the  command  line  contains  a  file  specification,  CHKDSK  will  examine  all  files  that 
match  the  specification  and  report  on  their  fragmentation — that  is,  on  whether  or  not 
their  sectors  are  contiguous  on  the  disk.  (Fragmented  files  can  degrade  the  performance  of 
the  system  because  of  the  time  required  to  move  the  drive  head  back  and  forth  across  the 
disk  to  reach  the  various  parts  of  the  file.)  Files  on  a  floppy  disk  can  be  collected  into  con¬ 
tiguous  sectors  by  copying  them  to  an  empty  floppy  disk.  Files  on  a  fixed  disk  can  be  col¬ 
lected  into  contiguous  sectors  by  backing  them  all  up  to  floppy  disks,  erasing  all  files  and 
subdirectories  on  the  fixed  disk,  and  then  restoring  the  files  from  the  floppy  disk. 

Warning:  CHKDSK  should  not  be  used  on  a  network  drive  or  on  a  drive  created  or 
affected  by  an  ASSIGN,  JOIN,  or  SUBST  command. 

Examples 

To  check  the  disk  in  the  current  drive,  type 

C>  CHKDSK  <Enter> 

If  CHKDSK  finds  no  errors,  a  report  such  as  the  following  is  displayed: 

Volume  HARDDISK  created  Jun  8,  1986  9; 34a 


21204992  bytes 
38912  bytes 
116736  bytes 
17055744  bytes 
20480  bytes 
3973120  bytes 


total  disk  space 
in  3  hidden  files 
in  53  directories 
in  715  user  files 
in  bad  sectors 
available  on  disk 


655360  bytes  total  memory 
566576  bytes  free 
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Note  that  the  line  containing  the  volume  name  and  creation  date  does  not  appear  if  the 
disk  has  not  been  assigned  a  volume  name. 

If  CHKDSK  finds  errors,  a  message  such  as  the  following  is  displayed: 

Errors  found,  F  parameter  not  specified. 

Corrections  will  not  be  written  to  disk. 

10  lost  clusters  found  in  3  chains. 

Convert  lost  chains  to  files  (Y/N) ? 

A  V  response  at  this  point  does  not  convert  the  lost  chains  to  files;  to  do  this,  enter  the 
CHKDSK  command  again  with  the  /F  switch  specified. 

To  correct  any  allocation  errors  found  by  the  CHKDSK  command,  type 

OCHKDSK  /F  <Enter> 

In  this  example,  CHKDSK  displays  its  usual  report,  followed  by  an  error  message: 

Volume  HARDDISK  created  Jun  8,  1986  9:34a 

21204992  bytes  total  disk  space 
38912  bytes  in  3  hidden  files 
116736  bytes  in  53  directories 
17055744  bytes  in  715  user  files 
20480  bytes  in  bad  sectors 
3973120  bytes  available  on  disk 

655360  bytes  total  memory 
566576  bytes  free 

10  lost  clusters  found  in  3  chains. 

Convert  lost  chains  to  files  (Y/N)  ? 

A  Y  response  causes  CHKDSK  to  recover  the  lost  chains  of  clusters  into  files  in  the  root 
directory,  giving  the  files  the  names  FILEOOOO.CHK,  FILEOOOl.CHK,  FILE0002.CHK,  and 
so  on.  An  TV  response  causes  CHKDSK  to  free  the  lost  chains  of  clusters  without  saving  the 
contents  to  files. 

To  check  all  files  in  the  directory  C:\SYSTEM  with  the  extension  .COM  for  fragmentation, 
type 

C>CHKDSK  C:\SYSTEM\*.COM  <Enter> 
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CHKDSK  displays  its  usual  report,  followed  by  a  list  of  fragmented  files: 

Volume  HARDDISK  created  Jun  8,  1986  9:34a 

21204992  bytes  total  disk  space 
38912  bytes  in  3  hidden  files 
116736  bytes  in  53  directories 
17055744  bytes  in  715  user  files 
20480  bytes  in  bad  sectors 
3973120  bytes  available  on  disk 

655360  bytes  total  memory 
566576  bytes  free 

C : \ S YSTEM\ALUSQ . COM 

Contains  2  non-contiguous  blocks. 

C : \SYSTEM\E JECT . COM 

Contains  4  non-contiguous  blocks. 

Messages 

.Does  not  exist. 

or 

..  Does  not  exist. 

The .  (alias  for  the  current  directory)  or  the ..  (alias  for  the  parent  directory)  entry  is 
missing.  ^ 

fitename  Is  cross  linked  on  cluster  n 

Two  or  more  files  have  been  assigned  the  same  cluster.  Make  a  copy  of  both  files  on 
another  disk  and  then  delete  them  from  the  disk  containing  the  error.  One  or  both  of  the 
resulting  files  may  contain  information  belonging  to  the  other  file. 

X  lost  clusters  found  inj'  chains. 

Convert  lost  chains  to  files  (Y/N)? 

Clusters  have  been  identified  that  are  not  assigned  to  any  existing  file.  If  the  /F  switch  was 
included  in  the  original  command  line,  respond  with  Y  to  convert  the  lost  clusters  to  files 
in  the  root  directory  of  the  disk  with  names  of  the  form  FILEn«nn.CHK.  If  desired,  the 
recovered  clusters  can  then  be  returned  to  the  free-disk-space  pool  by  erasing  the  .CHK 
files. 

Allocation  error,  size  adjusted. 

The  size  of  the  file  indicated  in  the  disk  directory  is  not  consistent  with  the  number  of 
clusters  allocated  to  the  file.  If  the  /F  switch  was  included  in  the  command  line,  the  file  is 
truncated  to  the  size  indicated  in  the  disk  directory. 

All  specified  fileCs)  are  contiguous. 

The  clusters  belonging  to  the  specified  file(s)  are  allocated  contiguously  (without 
fragmentation). 
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Cannot  CHDIR  to  pathname 
tree  past  this  point  not  processed. 

The  tree  directory  structure  of  the  disk  being  checked  cannot  be  traveled  to  the  specified 
directory.  This  message  indicates  severe  damage  to  the  disk’s  directories  or  files. 

Cannot  CHDK  to  root 
Processing  cannot  continue. 

In  traversing  the  tree  directory  structure  of  the  disk  being  checked,  CHKDSK  was  unable 
to  return  to  the  root  directory.  This  message  indicates  severe  damage  to  the  disk’s  directo¬ 
ries  or  files. 

Cannot  CHKDSK  a  Network  drive 

The  drive  containing  the  disk  to  be  checked  has  been  assigned  to  a  network. 

Cannot  CHKDSK  a  SUBSTed  or  ASSIGNed  drive 

The  drive  containing  the  disk  to  be  checked  has  been  substituted  or  assigned. 

Cannot  recover .  entry,  processing  continued. 

The  special  directory  entry .  (alias  for  the  current  directory)  is  defective. 

Cannot  recover ..  entry. 

Entry  has  a  had  attribute 

or 

Cannot  recover ..  entry. 

Entry  has  a  bad  link 

or 

Cannot  recover ..  entry. 

Entry  has  a  bad  size 

The  special  directory  entry ..  (alias  for  the  parent  directory  of  the  current  directory)  is 
defective  due  to  a  bad  attribute,  link,  or  size. 

CHDIR ..  failed,  trying  alternate  method. 

While  checking  the  tree  structure,  CHKDSK  was  unable  to  return  to  the  parent  directory 
of  the  current  directory.  It  will  attempt  to  return  to  that  directory  by  starting  over  at  the 
root  directory  and  searching  again. 

Contains  n  non-contiguous  blocks. 

The  clusters  assigned  to  the  specified  file  are  not  allocated  contiguously  on  the  disk. 

Directory  is  joined 

CHKDSK  cannot  process  directories  that  have  been  joined  using  the  JOIN  command.  Use 
the  JOIN  /D  command  to  unjoin  the  directories,  then  run  CHKDSK  again. 

Directory  is  totally  empty,  no .  or .. 

The  specified  directory  does  not  contain  the  usual  aliases  for  the  current  and  parent  direc¬ 
tories.  This  message  indicates  severe  damage  to  the  disk’s  directories  or  files.  Delete  the 
directory  and  recreate  it. 
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Disk  error  reading  FAT  n 

or 

Disk  error  writing  FAT  n 

One  of  the  file  allocation  tables  for  the  disk  being  checked  contains  a  defective  sector. 
MS-DOS  will  use  the  alternate  FAT  if  one  is  available.  It  is  advisable  to  copy  all  the  files  on 
the  disk  containing  the  defective  sector  to  another  disk. 

Errors  found,  F  parameter  not  specified. 

Corrections  will  not  be  written  to  disk. 

Errors  were  found  on  the  disk  being  checked,  but  the  /F  switch  was  not  included  in  the 
command  line. 

File  allocation  table  bad  drived: 

The  disk  is  not  an  MS-DOS  disk.  Repeat  CHKDSK  with  the  /F  option;  if  this  message  is 
displayed  again,  reformat  the  disk. 

File  not  found. 

CHKDSK  was  unable  to  find  the  specified  file. 

First  cluster  number  is  invalid,  entry  truncated. 

The  directory  entry  for  the  specified  file  contains  an  invalid  pointer  to  the  disk’s  data  area. 
If  the  /F  switch  was  included  in  the  command  line,  the  file  is  truncated  to  a  zero-length 
file. 

General  Failure  error  reading  driveX: 

The  format  of  the  disk  being  checked  is  not  compatible  with  MS-DOS  or  the  disk  has  not 
been  formatted  for  use  by  MS-DOS. 

Has  invalid  cluster,  file  truncated. 

The  file  directory  contains  an  invalid  pointer  to  the  disk’s  data  area.  If  the  /F  switch  was 
included  in  the  command  line,  the  file  is  truncated  to  a  zero-length  file. 

Incorrect  DOS  version 

The  version  of  CHKDSK  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insufficient  memory 
Processing  cannot  continue. 

The  computer  does  not  have  enough  memory  to  contain  the  tables  necessary  for  CHKDSK 
to  process  the  specified  disk. 

Insufficient  room  in  root  directory. 

Erase  files  in  root  and  repeat  CHKDSK. 

The  root  directory  is  full  and  does  not  have  room  for  the  entries  for  recovered  files.  Delete 
some  files  from  the  root  directory  of  the  disk  being  checked  and  rerun  the  CHKDSK 
program. 
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Invalid  current  directory 
Processing  cannot  continue. 

The  directory  structure  of  the  disk  is  so  badly  damaged  that  the  disk  is  unusable. 

Invalid  drive  specification 

The  CHKDSK  command  contained  an  invalid  disk  drive. 

Invalid  parameter 

One  of  the  switches  in  the  command  line  is  invalid. 

Invalid  sub-directory  entry. 

The  directory  name  specified  in  the  command  line  does  not  exist  or  is  invalid. 

Path  not  found. 

One  of  the  directories  in  the  path  specified  in  the  command  line  does  not  exist  or  is 
invalid. 

Probable  non-DOS  disk 
Continue  (Y/N)? 

The  disk  being  checked  was  not  formatted  by  MS-DOS  or  the  file  allocation  table  has  been 
severely  damaged  or  destroyed. 

Unrecoverable  error  in  directory. 

Convert  directory  to  file  (Y/N)? 

The  specified  directory  is  damaged  and  unusable.  If  the  /F  switch  was  included  in  the 
original  command  line,  respond  with  V  to  convert  the  damaged  directory  to  a  file  in  the 
root  directory  of  the  disk  with  a  name  of  the  form  FILEw«nn.CHK.  If  desired,  the  .CHK  file 
can  then  be  deleted.  Any  files  that  were  previously  reached  through  the  damaged  direc¬ 
tory  will  be  lost. 
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Clear  Screen 

Purpose 

Clears  the  video  display. 

Syntax 

CLS 

Description 

The  CLS  command  clears  the  video  display  and  displays  the  current  prompt. 

In  some  implementations  of  MS-DOS,  proper  operation  of  the  CLS  command  may  require 
installation  of  the  ANSI.SYS  console  driver  with  a  DEVICE= ANSI  SYS  comctm\A  in  the 
CONFIG.SYS  file. 

Examples 

To  clear  the  screen,  type 

C>CLS  <Enter> 

To  save  the  ANSI  escape  sequence  used  by  the  CLS  command  (ESC[2J)  into  a  file  named 
CLEAR.TXT,  type 

OCLS  >  CLEAR.TXT  <Enter> 


2.0  and  later 
Internal 
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COMMAND  1.0  and  later 

Command  Processor  External 


Purpose 

Loads  a  secondary  copy  of  the  MS-DOS  default  command  processor. 

Syntax 

COMMAND  [drive{\[path]  [device]  [/E:n]  l/P]  [/C  string] 
where: 
path 

device 
/E:w 

yp 

/C  string 

Description 

The  command  processor  is  the  module  of  the  operating  system  that  is  responsible  for 
issuing  prompts  to  the  user,  interpreting  commands,  loading  and  executing  transient  appli¬ 
cation  programs,  and  interpreting  batch  files.  The  file  COMMAND.COM  contains  the 
MS-DOS  default  command  processor,  or  shell.  It  is  ordinarily  loaded  from  the  root  direc¬ 
tory  of  the  system  disk  when  the  system  is  turned  on  or  restarted,  unless  the  SHELL  com¬ 
mand  is  used  in  the  CONFIG.SYS  file  to  specify  another  command  processor  or  an 
alternate  location  for  COMMAND.COM. 

With  versions  1.x,  COMMAND.COM  is  invoked  by  the  COMMAND  command  in  re¬ 
sponse  to  a  shell  prompt  or  within  a  batch  file.  A  second  copy  of  the  resident  portion  of 
COMMAND.COM  is  loaded  and  the  memory  occupied  by  the  original  resident  portion  is 
lost.  The  second  copy  of  the  transient  portion  simply  overlays  the  original  transient  por¬ 
tion.  (Versions  1.x  of  COMMAND  support  no  switches  or  other  parameters  and  any  speci¬ 
fied  in  the  command  line  are  ignored.)  With  versions  2.0  and  later,  the  new  copy  of 
COMMAND.COM  is  loaded  in  addition  to  the  parent  command  processor  and  serves 
as  a  secondary  command  processor. 


is  the  name  of  the  directory  to  be  searched  for  COMMAND.COM  when  the 
transient  portion  needs  to  be  reloaded;  a  drive  letter  can  be  included  with  ver¬ 
sions  2.0  and  later. 

is  the  name  of  a  character  device  to  be  used  instead  of  CON  for  the  command 
processor’s  input  and  output  (versions  2.0  and  later), 
is  the  initial  size,  in  bytes,  of  the  command  processor’s  environment  block 
(160-32768,  default  =  160)  (version  3.2). 

fixes  the  newly  loaded  command  processor  permanently  in  memory  (versions 
2.0  and  later). 

causes  the  command  processor  to  behave  as  a  transient  program  and  execute 
the  command  or  program  specified  by  mg  (versions  2.0  and  later). 
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The  path  parameter  specifies  the  location  of  the  COMMAND.COM  file  that  is  used  to 
reload  the  transient  part  of  the  command  processor  if  it  is  overlaid  by  application  pro¬ 
grams.  If  absent,  path  defaults  to  the  root  directory  of  the  system  (startup)  disk. 

The  device  parameter  allows  a  character  device  other  than  CON  to  be  used  by  the  com¬ 
mand  processor  for  input  and  output.  For  example,  use  of  AUX  as  the  device  parameter 
allows  a  personal  computer  to  be  controlled  from  a  terminal  attached  to  a  serial  port, 
instead  of  from  the  usual  built-in  keyboard  and  memory-mapped  video  display. 

The  secondary  copy  of  COMMAND.COM  ordinarily  remains  in  memory  and  serves  as  the 
active  command  processor  until  an  EXIT  command  is  entered.  If  a  /P  switch  is  used  with 
the  COMMAND  command,  the  new  copy  of  COMMAND.COM  is  fixed  in  memory  and  the 
EXIT  command  is  disabled.  In  such  cases,  the  memory  occupied  by  previously  loaded 
copies  of  COMMAND.COM  is  simply  lost. 

The  /E:  n  switch  controls  the  size  of  the  environment  block  initially  allocated  for  the 
command  processor.  The  default  size  of  the  block  is  l60  bytes,  but  the  /E:  n  switch  allows 
the  initial  allocation  to  be  as  large  as  32768  bytes.  This  switch  is  frequently  used  when 
COMMAND.COM  is  included  in  the  SHELL  command  in  the  CONFIG.SYS  file. 

When  the  /C  string  switch  is  included  in  the  command  line,  followed  by  a  string  desig¬ 
nating  a  command  or  program  name,  the  new  copy  of  COMMAND.COM  carries  out  the 
operation  specified  by  string  and  then  exits,  returning  control  to  its  parent  command  pro¬ 
cessor  or  other  program.  This  option  allows  a  batch  file  to  invoke  another  batch  file  and 
then  resume  its  own  execution.  (If  a  batch  file  names  another  batch  file  directly  without 
using  COMMAND  /C  string  as  an  intermediary,  the  first  batch  file  is  terminated.)  Note 
that  when  the  /C  string  switch  is  used  in  combination  with  other  switches,  it  must  be 
the  last  switch  in  the  command  line. 

A  secondary  copy  of  COMMAND.COM  always  inherits  a  copy  of  the  environment  of 
the  command  processor  or  other  program  that  loaded  it.  Changes  made  to  the  new 
COMMAND. COM’s  environment  with  a  SET,  PROMPT,  or  PATH  command  do  not  affect 
the  environment  of  any  previously  loaded  program  or  command  processor. 

Examples 

To  execute  the  batch  file  MENU2.BAT  from  the  batch  file  MENU1.BAT  and  then  resume 
execution  of  MENU1.BAT,  include  the  following  line  in  MENU1.BAT: 

COMMAND  /C  MENU2 

To  cause  COMMAND.COM  to  be  loaded  from  the  directory  \  SYSTEM  on  drive  C  rather 
than  from  the  root  directory  and  to  allocate  an  initial  environment  block  of  1024  bytes, 
include  the  following  line  in  the  CONFIG.SYS  file: 

SHELL=C:\SYSTEM\COMMAND.COM  C:\SYSTEM  /P  /E:1024 
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Messages 

Bad  or  missing  command  interpreter 

The  file  COMMAND.COM  is  not  present  in  the  root  directory  of  the  system  disk  and  no 
SHELL  command  is  present  to  specify  an  alternate  command  processor  file  or  location,  or 
the  location  specified  for  COMMAND.COM  in  a  SHELL  command  is  not  correct.  This  mes¬ 
sage  may  also  be  seen  if  COMMAND.COM  is  moved  from  its  original  location  after  the 
system  is  booted. 

Invalid  device 

The  character  device  specified  in  the  command  line  is  not  valid  or  does  not  exist. 

Invalid  environment  size  specified 

The  value  supplied  with  the  /E:  n  switch  was  less  than  l60  bytes  or  greater  than  32768 
bytes. 
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COMP  IBM 

Compare  Files  External 


Purpose 

Compares  two  files  or  sets  of  files.  This  command  is  available  only  with  PC-DOS. 

Syntax 

COMP  [primary]  [secondary] 
where: 

primary  is  the  name  of  the  file  to  be  compared  against  and  can  be  preceded  by  a 

drive  and/or  path;  wildcard  characters  are  permitted  in  the  filename. 
secondary  is  the  name  of  the  file  to  be  compared  with  primary  and  can  be  preceded 

by  a  drive  and/or  path;  wildcard  characters  are  permitted  in  the  filename. 

Description 

The  COMP  command  compares  one  file  or  set  of  files  with  another.  As  each  pair  of  files  is 
compared,  the  program  reports  whether  the  files  are  identical,  different  in  size,  or  the 
same  size  but  different  in  content. 

The  primary  and  secondary  parameters  can  be  any  combination  of  drive,  path,  and  file¬ 
name,  optionally  including  wildcards  to  allow  sets  of  files  to  be  compared.  (With  versions 
1.x,  using  wildcards  does  not  cause  multiple  file  comparisons — only  the  first  secondary 
file  whose  name  matches  the  first  primary  filename  is  compared.)  The  primary  parameter 
generally  designates  the  specific  files  to  be  compared;  the  secondary  parameter  is  usually 
only  a  drive  and/or  path,  except  when  the  files  being  compared  have  different  names  or 
extensions. 

If  both  primary  and  secondary  are  omitted  from  the  command  line,  the  COMP  program 
prompts  for  them  interactively.  If  primary  is  given  as  a  drive  or  path  only,  COMP  assumes 
*.*  to  be  the  primary  file.  If  secondary  is  given  as  a  drive  or  path  only,  COMP  compares  all 
files  on  that  drive  or  path  whose  filenames  match  those  of  the  primary  files. 

The  COMP  command  is  included  only  with  PC-DOS.  MS-DOS  versions  2.0  and  later 
provide  a  similar  function  in  the  PC  command,  which  also  displays  the  differences  be¬ 
tween  files. 

Examples 

To  compare  the  file  MYFILE.DAT  on  the  disk  in  drive  A  with  the  file  LEDGER.DAT  on  the 
disk  in  drive  B,  type 

C>C0MP  A: MYFILE.DAT  B: LEDGER. DAT  <Enter> 
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To  compare  all  the  files  in  the  current  directory  of  the  disk  in  drive  A  with  the 
corresponding  files  in  the  current  directory  of  the  disk  in  drive  D,  type 

OCOMP  A:*.»  D:  <Enter> 

To  compare  all  the  files  with  the  extension  .ASM  in  the  directory  C:\SOURCE  with  the 
corresponding  files  with  extension  .BAK  on  the  disk  in  drive  B,  type 

OcOMP  C:\SOURCE\*.ASM  B:*.BAK  <Enter> 

Messages 

10  mismatches  -  ending  compare 

The  primary  and  secondary  files  are  the  same  size  but  have  more  than  10  internal  differ¬ 
ences.  The  compare  operation  on  this  pair  of  files  is  aborted  and  COMP  proceeds  to  the 
next  pair  of  files,  if  any. 

fitename  SM.dfUenatne 

This  informational  message  shows  the  full  filenames  of  the  two  files  currently  being 
compared. 

Access  Denied 

An  attempt  was  made  to  compare  a  locked  file. 

Cannot  compare  file  to  itself 

An  attempt  was  made  to  compare  a  file  with  itself. 

Compare  error  at  OFFSET  nn 

FUel  =  ffit 

FUe2=nn 

This  informational  message  itemizes  the  first  10  differences  in  data  between  the  two  files 
being  compared  (if  the  files  are  the  same  size),  displaying  the  file  offset  and  the  differing 
bytes  from  each  file  as  hexadecimal  values. 

Compare  more  files  (Y/N)? 

After  all  specified  pairs  of  files  have  been  compared,  the  COMP  program  allows  the  entry 
of  another  pair  of  file  specifications.  Respond  with  Y  or  press  Enter  to  continue;  respond 
with  N  to  terminate  the  COMP  program. 

Enter  2nd  file  name  or  drive  id 

If  the  secondary  filename  was  not  specified  in  the  COMP  command,  this  message  prompts 
the  user  to  enter  it  (or  a  path,  if  the  secondary  file  has  the  same  name  as  the  primary  file). 

Enter  primary  file  name 

If  no  parameter  was  entered  after  COMP,  this  message  prompts  the  user  to  enter  the  pri¬ 
mary  filename.  If  a  drive  or  path  is  specified,  COMP  assumes  *.♦  for  the  primary  filename. 

EOF  mark  not  found 

The  last  byte  at  the  logical  end  of  the  file  was  not  a  Control-Z  character  (^Z,  or  lAH).  This 
message  is  commonly  seen  during  comparison  of  two  files  that  are  not  ASCII  text  files, 
such  as  executable  program  files. 
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Files  compare  OK 

The  files  being  compared  were  the  same  length  and  contained  identical  data. 

File  not  found 

The  specified  filename  was  invalid  or  the  file  does  not  exist. 

Files  are  different  sizes 

The  two  files  being  compared  have  different  sizes  recorded  in  the  directory.  No  com¬ 
parison  on  the  data  within  the  files  is  attempted. 

File  sharing  conflict 

COMP  is  unable  to  compare  the  two  current  files  because  one  of  the  files  is  in  use  by 
another  process. 

Incorrect  DOS  version 

The  version  of  COMP  is  not  compatible  with  the  version  of  PC-DOS  that  is  running. 

Insufficient  memory 

The  available  system  memory  is  insufficient  to  run  the  COMP  program. 

Invalid  drive  specification 

The  drive  specification  in  primary  or  secondary  is  invalid  or  does  not  exist. 

Invalid  path 

The  path  or  directory  in  primary  or  secondary  is  invalid  or  does  not  exist. 

Too  many  files  open 

No  more  system  file  handles  are  available.  Increase  the  value  of  the  FILES  command  in  the 
CONFIG.SYS  file  and  restart  the  system. 
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CONFIG.SYS  2.0  and  later 

System  Configuration  File 

Purpose 

Allows  the  user  to  configure  the  operating  system. 

Description 

The  CONFIG.SYS  file  is  an  ASCII  text  file  that  MS-DOS  processes  during  initialization 
(when  the  system  is  turned  on  or  restarted).  It  allows  the  user  to  configure  certain  aspects 
of  the  operating  system,  such  as  the  number  of  internal  disk  buffers  allocated,  the  number 
of  files  that  can  be  open  at  one  time,  the  formats  for  date  and  currency,  and  the  name  and 
location  of  the  executable  file  containing  the  command  processor.  CONFIG.SYS  can  also 
contain  commands  that  extend  the  system  with  installable  device  drivers  for  terminal 
emulation,  virtual  disks  or  RAMdisks,  extended  or  expanded  memory,  and  other  special 
peripheral  devices. 

The  CONFIG.SYS  file  can  be  created  or  modified  with  EDLIN  or  with  any  other  editor  or 
word  processor  that  can  produce  ordinary  ASCII  text  files  (nondocument  files)  and  save 
them  to  disk.  The  CONFIG.SYS  file  must  be  in  the  root  directory  of  the  disk  that  is  used  to 
start  the  operating  system  in  order  for  it  to  be  processed  during  system  initialization. 

When  changes  are  made  to  the  CONFIG.SYS  file,  they  do  not  take  effect  until  the  system 
is  restarted. 

Commands  in  the  CONFIG.SYS  file  take  the  form 
command  [=]  value 

(Note  that  the  equal  sign  is  optional;  any  other  valid  MS-DOS  separator  [semicolon,  tab,  or 
space]  can  be  used  instead.)  The  commands  supported  are 

Command  Action 

BREAK  Controls  extended  checking  for  Control-C. 

BUFFERS  .  Specifies  the  number  of  internal  disk-sector  buffers  available  for  use  by 

MS-DOS  when  reading  from  or  writing  to  a  disk. 

COUNTRY  Controls  date,  time,  and  currency  formatting. 

DEVICE  Specifies  the  filename  of  an  installable  device  driver. 

DRIVPARM  Redefines  the  default  characteristics  of  the  resident  MS-DOS  block 

device(s)  (version  3.2). 

FCBS  Specifies  the  maximum  number  of  simultaneously  open  file  control  blocks 

(versions  3.0  and  later). 

(more) 
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Command  Action 

FILES  Specifies  the  maximum  number  of  simultaneously  open  files  controlled  by 

handles. 

L  ASTDRIVE  Sets  the  highest  valid  drive  letter  (versions  3.0  and  later). 

SHELL  Specifies  the  filename  (and  optionally  the  drive  and/or  path)  of  the  system 

command  processor. 

STACKS  Sets  the  number  and  size  of  stack  frames  for  the  system. 

Each  of  these  commands  is  discussed  in  detail  on  the  following  pages. 

Message 

Unrecognized  command  in  CONFIG.SYS 

A  command  in  the  CONFIG.SYS  file  was  misspelled,  an  invalid  parameter  was  used,  or  a 
command  was  included  that  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 
Correct  the  CONFIG.SYS  file  and  restart  the  system. 
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CONFIG.SYS:  BREAK  2  0  and  later 

Configure  Control-C  Checking 


Purpose 

Sets  or  clears  MS-DOS’s  internal  flag  for  Control-C  checking. 

Syntax 

BREAK=ON  I  OFF 

Description 

Pressing  Ctrl-C  or  Ctrl-Break  while  a  program  is  running  ordinarily  terminates  the  pro¬ 
gram,  unless  the  program  itself  contains  instructions  that  disable  MS-DOS’s  Control-C 
handling.  As  a  rule,  MS-DOS  checks  the  keyboard  for  a  Control-C  only  when  a  character  is 
read  from  or  written  to  a  character  device  (keyboard,  screen,  printer,  or  auxiliary  port). 
Therefore,  if  a  program  executes  for  long  periods  without  performing  such  character  I/O, 
detection  of  the  user’s  entry  of  a  Control-C  may  be  delayed.  The  BREAK=ON  command 
causes  MS-DOS  to  also  check  the  keyboard  for  a  Control-C  at  the  time  of  each  system  call 
(which  slows  the  system  somewhat);  the  BREAK=OFF  command  disables  such  extended 
Control-C  checking.  The  default  setting  for  BREAK  is  off. 

Extended  Control-C  checking  can  also  be  enabled  or  disabled  at  the  command  prompt 
with  the  interactive  form  of  the  BREAK  command  whenever  the  system  is  running. 

Example 

To  enable  extended  Control-C  checking  during  MS-DOS  disk  operations,  insert  the  line 

BREAK=ON 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Message 

Unrecognized  command  in  CONFIG.SYS 

The  setting  supplied  for  the  BREAK  command  was  not  ON  or  OFF.  Correct  the 
CONFIG.SYS  file  and  restart  the  system. 
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CONFIG.SYS:  BUFFERS  2.0  and  later 

Configure  Internal  Disk  Buffers 


Purpose 

Sets  the  number  of  MS-DOS’s  internal  disk  buffers. 

Syntax 

BUFFERS=nn 

where: 

nn  is  the  number  of  buffers  (1-99,  default  =  2;  default  =  3  for  IBM  PCAT  and 

compatibles). 

Description 

MS-DOS  maintains  a  set  of  internal  buffers  (sometimes  referred  to  as  a  disk  cache)  in 
which  it  keeps  copies  of  the  sectors  most  recently  read  from  or  written  to  the  disk.  When¬ 
ever  a  program  requests  a  disk  read,  MS-DOS  first  searches  the  disk  buffers  to  determine 
whether  a  copy  of  the  disk  sector  containing  the  required  data  is  already  present  in  RAM. 

If  the  sector  is  found,  the  actual  disk  access  is  bypassed.  This  technique  can  significantly 
improve  the  overall  performance  of  the  disk  operating  system. 

By  using  the  BUFFERS  command  in  the  CONFIG.SYS  file,  the  user  can  control  the  number 
of  buffers  in  MS-DOS’s  disk  cache.  The  default  number  of  buffers  is  2  for  an  IBM  PC, 

PC/XT,  or  compatible  and  3  for  an  IBM  PC/AT  or  compatible.  The  optimum  nvimber  of 
buffers  varies,  depending  in  part  on  the  characteristics  and  types  of  the  system  disk  drives, 
the  types  of  application  programs  used  on  the  system,  the  number  and  levels  of  subdirec¬ 
tories  in  the  file  structure,  and  the  amount  of  RAM  in  the  system. 

If  the  system  has  only  floppy-disk  drives,  the  default  setting  of  2  buffers  is  sufficient.  If  the 
system  includes  a  fixed  disk,  increasing  the  number  of  buffers  to  10  or  so  typically  speeds 
up  overall  system  operation.  Configuring  the  system  for  too  many  buffers,  however,  can 
actually  degrade  the  performance  of  the  system. 

Increases  in  the  number  of  buffers  should  be  tailored  to  the  type  of  application  most  fre¬ 
quently  used.  For  example,  allocation  of  extra  disk  buffers  will  not  improve  the  perfor¬ 
mance  of  programs  that  use  primarily  sequential  file  access  but  may  considerably  enhance 
the  execution  times  of  programs  that  perform  random  access  on  a  relatively  small  number 
of  disk  records  (such  as  the  index  for  a  database  file).  In  addition,  if  the  system  has  many 
subdirectories  organized  in  several  levels,  increasing  the  number  of  buffers  can  signifi¬ 
cantly  increase  the  speed  of  disk  operations. 

The  ideal  number  of  buffers  for  a  given  system  is  difficult  to  predict  because  of  the  interac¬ 
tions  between  the  access  time  of  the  disk,  the  speed  of  the  central  processing  unit,  and  the 
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RAM  requirements  and  disk  access  behavior  of  the  mix  of  application  programs.  However, 
a  reasonably  optimal  number  of  buffers  can  be  quickly  estimated  experimentally  by  in¬ 
creasing  the  number  of  buffers  in  increments  of  five  or  so,  restarting  the  system,  perform¬ 
ing  some  simple  timing  tests  on  the  most  frequently  used  application  programs,  and 
observing  at  what  number  of  buffers  system  performance  begins  to  degrade. 

Example 

To  allocate  20  internal  disk  buffers,  insert  the  line 

BUFFERS=20 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Message 

Unrecognized  command  in  CONFIG.SYS 

The  value  supplied  for  the  BUFFERS  command  was  not  a  number  in  the  range  1  through 

99. 
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CONFIG.SYS:  COUNTRY  2.1  and  later 

Set  Country  Code 


Purpose 

Configures  MS-DOS’s  internationalization  support  for  a  specific  country. 

Syntax 

COUNTRY=Mnn 

where: 

nnn  is  the  international  telephone  dialing  prefix  for  the  country  (001-999,  default  = 

001): 


Australia  06l 

Belgium  032 

Denmark  045 

Finland  358 

France  033 

Israel  972 

Italy  039 

Netherlands  031 

Norway  047 

Spain  034 

Sweden  046 

Switzerland  041 

United  Kingdom  044 

USA  001 

West  Germany  049 


N<ae:  In  versions  2.x  (except  2.0),  nnn  is  01  through  99.  Individual  computer  manufactur¬ 
ers  determine  the  specific  codes  supported  by  their  versions  of  MS-DOS. 

Description 

The  COUNTRY  command  enables  the  user  to  tailor  MS-DOS’s  date,  time,  and  currency 
displays  for  a  specific  coimtry.  This  capability,  termed  internationalization  support,  is 
achieved  through  use  of  a  country  code  that  controls  the  contents  of  the  table  MS-DOS 
uses  to  format  these  displays  (including  numeric  separators).  (The  internationalization 
table  is  made  available  to  application  programs  through  Interrupt  21H  Function  38H.) 
Beginning  with  version  3.0,  PC-DOS  also  supports  the  COUNTRY  command. 
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Example 

In  West  Germany,  the  format  for  the  date  is  dd.mm.yy.  To  configure  MS-DOS  to  use  this 
date  format,  insert  the  line 

COUNTRY=049 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Message 

Invalid  country  code 

The  specified  country  code  is  not  supported  by  the  version  of  MS-DOS  that  is  running. 
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CONFIG.SYS:  DEVICE  2.0  and  later 

Install  Device  Driver 


Purpose 

Loads  and  links  an  installable  device  driver  into  the  operating  system  during  initialization. 

Syntax 

\yEYlCE=[driw\[path]filenarne  [optum^ 
where: 

filename  is  the  name  of  the  device-driver  file,  optionally  preceded  by  a  drive  and/or 
path. 

options  specifies  any  switches  or  other  parameters  needed  by  the  device  driver;  the 

DEVICE  command  itself  has  no  switches. 

Description 

Device  drivers  are  the  modules  of  the  operating  system  that  control  the  interface  between 
the  operating  system  and  peripheral  devices  such  as  disk  drives,  magnetic-tape  drives, 

CRT  terminals,  and  printers. 

As  supplied,  MS-DOS  already  contains  device  drivers  for  the  keyboard,  video  display,  serial 
port,  printer,  real-time  clock,  and  disk  devices.  Device  drivers  for  additional  peripheral 
devices  can  be  linked  into  the  operating  system  by  adding  a  DEVICE  command  to  the 
CONFIG.SYS  file,  placing  the  file  containing  the  device  driver  on  the  system  startup  disk 
(or  at  the  location  specified  by  the  drive:  and/or  path  parameter),  and  restarting  the 
computer. 

If  a  drive  other  than  the  one  containing  the  system  disk  is  named  as  the  location  of  the 
device  driver,  that  drive  must  either  be  accessible  via  the  system’s  default  disk  driver  or  be 
a  drive  configured  with  a  previous  DEVICE  command. 

Most  OEM  implementations  of  version  3.2  provide  three  installable  device  drivers: 
ANSI.SYS,  which  allows  the  video  display  and  keyboard  to  be  controlled  by  ANSI  standard 
escape  sequences;  DRIVER.SYS,  which  supports  external  disk  drives;  and  RAMDRIVE.SYS 
(VDISK.SYS  with  PC-DOS),  which  uses  a  portion  of  the  machine’s  RAM  to  emulate  a  disk 
drive.  See  USER  COMMANDS:  ansi.sys;  driver.sys;  ramdrive.sys;  vdisk.sys. 

Many  manufacturers  of  add-on  products  for  MS-DOS  machines  (such  as  network  interfaces 
or  Lotus/Intel/Microsoft  Expanded  Memory  boards)  also  supply  installable  device  drivers 
for  use  with  their  hardware.  For  information  concerning  these  drivers,  see  the  product 
manufacturer’s  user’s  manual. 
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Examples 

To  load  the  ANSI  standard  console  driver,  insert  the  line 

DEVICE=ANSI.SYS 

into  the  CONFIG.SYS  file,  place  the  file  ANSI.SYS  in  the  root  directory  of  the  system  disk, 
and  restart  the  system. 

To  load  the  RAMDRIVE.SYS  driver  located  in  the  \DRIVERS  directory  on  the  disk  in  drive 
A,  configuring  it  for  1024  KB  in  extended  memory,  insert  the  line 

DEVICE=A: \DRI VERS \RAMDRIVE. SYS  1024  /E 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Messages 

Bad  or  missing  filename 

The  filename  specified  in  the  DEVICE  command  is  invalid  or  does  not  exist  or  the  file 
does  not  contain  a  valid  MS-DOS  installable  device  driver. 

Sector  size  too  large  in  file  filename 

The  specified  installable  device  driver  uses  a  sector  size  that  is  larger  than  the  sector  size 
used  by  any  of  the  system’s  default  disk  drivers.  Such  a  driver  cannot  be  used  because 
MS-DOS’s  internal  disk  buffers  will  not  be  large  enough  to  hold  a  sector  read  from  the 
device. 
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CONFIG.SYS:  DRIVPARM  32 

Set  Block-Device  Parameters 


Purpose 

Alters  the  system’s  list  of  characteristics  for  an  existing  block  device. 

Syntax 

DRIVPARM=/D:w[/C]  [/F:w]  [/H:w]  [/N]  l/S:n]  [/T:w] 
where: 

/D:  n  is  the  drive  number  (0-255;  0  =  A,  1  =  B,  etc.)  and  must  always  be  the  first 

switch  in  the  command  line. 

/C  indicates  that  the  device  provides  door-lock-status  support. 

/F:  n  is  a  form-factor  index  from  the  following  table  (default  =  2  if  the  DRIVPARM 

command  is  present  but  this  switch  is  omitted): 

0  320  KB  or  360  KB 

1  1.2  MB 

2  720  KB 

3  8-inch  single-density  floppy  disk 

4  8-inch  double-density  floppy  disk 

5  Fixed  disk 

6  Tape  drive 

7  Other 

/H:  n  is  the  number  of  read/write  heads  (1-99). 

/N  indicates  that  the  block  device  is  not  removable. 

/S:  n  is  the  number  of  sectors  per  track  (1-99). 

/T:  n  is  the  number  of  tracks  per  side  (1-999). 

Note:  The  DRIVPARM  command  must  not  be  used  to  specify  device  characteristics  that 
the  device  driver  is  not  capable  of  supporting. 

Description 

Whenever  the  device  driver  for  a  block  device  such  as  a  disk  drive  or  magnetic-tape  drive 
performs  input  or  output,  it  refers  to  an  internal  table  of  characteristics  for  the  device  that 
allows  it  to  convert  logical  addresses  to  physical  addresses.  The  DRIVPARM  command 
modifies  the  default  MS-DOS  values  in  the  table  of  characteristics  for  a  particular  block 
device  during  system  initialization  (when  the  computer  is  turned  on  or  restarted).  Multiple 
DRIVPARM  commands,  each  modifying  the  characteristics  of  a  different  block  device,  can 
be  included  in  the  same  CONFIG.SYS  file.  Any  characteristics  not  specifically  altered  in 
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the  DRIVPARM  command  for  a  particular  device  retain  their  original  values,  except  for 
/F: «,  which  defaults  to  2. 

DRIVPARM  commands  that  alter  the  characteristics  for  block  devices  controlled  by  install¬ 
able  device  drivers  must  follow  the  DEVICE  command  that  loads  the  device  driver  itself. 

Example 

Assume  that  drive  B  is  a  floppy-disk  drive  originally  configured  for  40  tracks  with  8  sectors 
per  track.  To  reconfigure  the  drive  to  read  or  write  80  tracks  of  9  sectors  each,  insert  the 
line 

DRIVPARM=/D;1  /S:9  /T:80 

into  the  CONFIG.SYS  file  and  restart  the  system.  For  this  command  to  be  valid  the  drive 
must  be  capable  of  supporting  these  parameters. 

Message 

Unrecognized  command  in  CONFIG.SYS 

An  invalid  parameter  was  specified  in  a  DRIVPARM  command. 
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CONFIG.SYS;  FCBS  3.0  and  later 

Set  Maximum  Open  Files  Using  File  Control  Blocks  (FCBs) 


Purpose 

Configures  the  maximum  number  of  files  that  can  be  open  concurrently  using  file  control 
blocks  (FCBs).  This  command  has  no  practical  effect  unless  either  the  file-sharing  support 
module  SHARE.EXE  or  networking  support  has  been  loaded. 

Syntax 

FCBS=m,p 

where: 

m  is  the  maximum  number  of  files  that  can  be  open  concurrently  using  FCBs  (1-255, 
default  =  4). 

p  is  the  number  of  files  opened  with  FCBs  that  are  protected  against  automatic  closure 
(0-m,  default  =  0). 

Description 

MS-DOS  supports  two  methods  of  file  access;  file  control  blocks  and  file  handles.  A  file 
control  block  is  a  data  structure  that  stores  information  about  an  open  file.  It  resides  inside 
an  application  program’s  memory  space  and  is  accessed  by  both  MS-DOS  and  the  applica¬ 
tion.  Isee  USER  COMMANDS:  config.sys:  files  for  information  on  file  handles.) 

In  a  network  environment,  a  large  number  of  active  FCBs  or  improper  use  of  FCBs  by 
an  application  can  seriously  degrade  the  performance  of  the  network  as  a  whole.  Conse¬ 
quently,  MS-DOS  versions  3.0  and  later  provide  the  FCBS  command  to  enable  the  user  to 
limit  the  number  of  files  that  can  be  open  concurrently  using  FCBs  if  either  the  file-sharing 
support  module  SHARE.EXE  (see  USER  COMMANDS:  share)  or  network  support  has 
been  loaded.  If  an  application  program  attempts  to  exceed  the  specified  number  of  files, 
MS-DOS  closes  the  file  with  the  least  recently  used  FCB. 

The  p  parameter  in  the  FCBS  command  line  allows  the  user  to  protect  files  from  unilateral 
closure  by  MS-DOS.  The  value  of  p  is  the  number  of  files,  counting  from  the  first  file 
opened  using  an  FCB,  that  cannot  be  closed  automatically. 

If  the  current  value  of  FCBS  is  4,0  (the  default)  when  the  file-sharing  module  SHARE.EXE 
or  network  support  is  loaded,  MS-DOS  automatically  increases  the  maximum  number  of 
files  that  can  be  open  concurrently  to  16  and  the  number  of  files  protected  against  automa¬ 
tic  closure  to  8.  (When  multiple  FCBs  refer  to  the  same  file,  the  file  is  counted  only  once.) 
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Examples 

To  set  the  maximum  number  of  files  that  can  be  concurrently  open  using  FCBs  to  10  and 
protect  none  of  the  FCBopened  files  against  automatic  closure  by  MS-DOS,  insert  the  line 

FCBS=10, 0 

into  the  CONFIG.SYS  file  and  restart  the  system. 

To  set  the  maximum  number  of  files  that  can  be  concurrently  open  using  FCBs  to  8  but 
protect  the  first  4  FCB-opened  files  against  automatic  closure  by  MS-DOS,  insert  the  line 

FCBS=8,4 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Message 

Unrecognized  command  in  CONFIG.SYS 

An  invalid  number  was  specified  as  one  of  the  parameters  in  the  FCBS  command. 
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CONnG.SYS:  FILES  2.0  and  later 

Set  Maximum  Open  Files  Using  Handles 


Purpose 

Configures  the  maximum  number  of  files  and/or  devices  that  can  be  open  concurrently 
using  file  handles. 

Syntax 

FILES=« 

where: 

n  is  the  maximum  number  of  files  and  devices  that  can  be  open  concurrently  using  file 
handles  (8-255,  default  =  8). 

Description 

MS-DOS  supports  two  methods  of  file  access:  file  handles  and  file  control  blocks  (FCBs). 
During  initialization,  MS-DOS  allocates  a  data  structure  that  holds  information  about  files 
and/or  devices  opened  with  the  handle,  or  extended-file-management,  function  calls.  This 
structure  resides  inside  the  operating  system’s  memory  space  and  is  accessed  only  by 
MS-DOS.  iSee  USER  COMMANDS:  config.sys:  fobs.)  The  default  size  of  this  data  structure 
allows  8  files  and/or  devices  to  be  open  concurrently  using  the  file-handle  functions.  The 
FILES  command  enables  the  user  to  change  the  size  of  the  data  structure.  (Note  that  in¬ 
creasing  the  size  of  the  data  structure  decreases  the  amount  of  RAM  available  to  applica¬ 
tion  programs.) 

The  FILES  command  controls  the  maximum  number  of  files  and/or  devices  opened  with 
handles  for  all  active  processes  in  the  system  combined.  The  limit  on  the  number  of  files 
and/or  devices  opened  for  a  single  process  using  handles  is  20  or  the  number  of  entries  in 
the  allocated  data  structure,  whichever  is  less.  Five  of  the  20  possible  handles  for  a  given 
process  are  automatically  assigned  to  standard  input,  standard  output,  standard  error,  stan¬ 
dard  auxiliary,  and  standard  list.  However,  since  standard  input,  standard  output,  and 
standard  error  all  default  to  the  same  device  (CON),  only  three  of  the  allocated  data- 
structure  entries  are  actually  expended.  In  addition,  the  preassigned  standard  device 
handles  for  a  process  can  be  closed  and  reused  for  other  files  and  devices,  if  necessary. 
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Example 

To  set  the  maximum  number  of  files  and/or  devices  that  can  be  concurrently  open  using 
the  handle  functions  to  20,  insert  the  line 

FILES=20 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Message 

Unrecognized  command  in  CONFIG.SYS 

An  invalid  number  was  specified  in  the  FILES  command. 
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CONFIG.SYS:  LASTDRIVE  3.0  and  later 

Set  Highest  Logical  Drive 


Purpose 

Defines  the  highest  letter  that  MS-DOS  will  recognize  as  a  disk-drive  code. 

Syntax 

L  ASTDRI  VE=  drive 
where: 

drive  is  a  single  letter  (A-Z). 

Description 

MS-DOS  block  devices  (floppy-disk  drives,  fixed-disk  drives,  and  magnetic-tape  drives) 
are  referred  to  by  logical  drive  codes  consisting  of  a  single  letter  from  A  through  Z.  In  most 
MS-DOS  systems,  drives  A  and  B  are  floppy-disk  drives,  drive  C  is  a  fixed  disk,  and  drives 
D  and  above  are  such  devices  as  additional  fixed  disks,  RAMdisks,  or  network  volumes.  In 
some  cases,  a  single  physical  drive  (such  as  a  very  large  fixed  disk)  is  partitioned  into  two 
or  more  logical  drives,  each  of  which  is  assigned  a  drive  letter. 

MS-DOS  validates  the  drive  code  in  a  command  or  filename  before  carrying  out  a  com¬ 
mand.  In  the  default  case,  MS-DOS  recognizes  a  maximum  of  five  drives  (A-E),  depend¬ 
ing  on  the  total  number  of  default  devices  and  devices  incorporated  into  the  system  using 
installable  device  drivers.  (MS-DOS  does  not  consider  a  drive  letter  valid  unless  it  refers  to 
a  physical  or  logical  device.)  The  LASTDRIVE  command  configures  MS-DOS  to  accept 
additional  drive  codes,  to  a  total  of  26  (A-Z).  This  also  makes  it  possible  to  use  fictitious 
drive  letters  with  the  SUBST  command  to  assign  a  drive  letter  to  a  subdirectory. 

If  the  letter  code  for  a  LASTDRIVE  command  specifies  fewer  drives  than  are  physically 
present  in  the  system  (including  installed  device  drivers),  MS-DOS  uses  the  actual  number 
of  physical  drives. 

Example 

To  configure  MS-DOS  to  recognize  a  maximum  of  eight  logical  disk  drives,  insert  the  line 

LASTDRIVE=H 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Message 

Unrecognized  command  in  CONFIG.SYS 

An  illegal  value  was  specified  in  the  LASTDRIVE  command. 
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CONFIG.SYS;  SHELL  2.0  and  later 

Specify  Command  Processor 


Purpose 

Defines  the  name  and,  optionally,  the  location  of  the  file  that  contains  the  operating 
system’s  command  processor. 

Syntax 

S}:YElL^[drive'][path] filename  [options] 
where: 

filename  is  the  name  of  the  file  containing  the  command  processor,  optionally  pre¬ 
ceded  by  a  drive  and/or  path. 

options  specifies  any  switches  and  other  parameters  needed  by  the  designated  com¬ 

mand  processor;  the  SHELL  command  itself  has  no  switches. 

Description 

The  command  processor,  or  shell,  is  the  user’s  interface  to  the  operating  system.  It  is 
responsible  for  parsing  and  carrying  out  the  user’s  commands,  including  the  loading  and 
execution  of  other  programs  from  the  disk.  MS-DOS  uses  the  SHELL  command  in  the 
CONFIG.SYS  file  to  locate  and  load  the  command  interpreter  for  the  system  during  its 
initialization  process. 

The  default  shell  for  MS-DOS  is  the  file  COMMAND.COM.  This  file  is  loaded  by  MS-DOS 
from  the  root  directory  of  the  system  disk  if  no  SHELL  command  is  found  in  the 
CONFIG.SYS  file  or  if  no  CONFIG.SYS  file  exists. 

The  most  common  use  of  the  SHELL  command  is  simply  to  advise  MS-DOS  that 
COMMAND.COM  is  stored  in  a  location  other  than  the  root  directory;  MS-DOS  then  sets 
the  COMSPEC  variable  in  the  environment  block  to  COMMAND.COM,  preceded  by  the 
location  specified  in  the  SHELL  command.  (This  can  be  verified  by  typing  the  SET  com¬ 
mand  at  the  command  prompt.)  Another  common  use  of  SHELL  is  to  specify  switches  or 
other  parameters  for  COMMAND.COM  itself  isee  USER  COMMANDS:  command). 

Example 

To  specify  the  file  VISUAL.COM  in  the  root  directory  of  drive  C  as  the  system’s  command 
processor,  insert  the  line 

SHELL=C :  WISUAL .  COM 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Message 

Bad  or  missing  command  interpreter 

The  path  or  filename  in  the  SHELL  command  is  invalid  or  the  file  does  not  exist. 
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CONFIG.SYS:  STACKS  32 

Configure  Internal  Stacks 


Purpose 

Defines  the  number  and  size  of  stacks  for  system  interrupt  handlers. 

Syntax 

STACKS=  number, size 
where: 

number  is  the  number  of  stacks  allocated  for  use  by  interrupt  handlers  (8-64,  default  = 

9). 

size  is  the  size  of  each  stack  in  bytes  (32-512,  default  =  128). 

Description 

Each  time  certain  hardware  interrupts  occur  (02H,  08-0EH,  70H,  and  72-77H),  MS-DOS 
version  3.2  switches  to  an  internal  stack  before  transferring  control  to  the  handler  that  will 
service  the  interrupt.  In  the  case  of  nested  interrupts,  MS-DOS  checks  to  ensure  that  both 
interrupts  do  not  get  the  same  stack.  After  the  interrupt  has  been  processed,  the  stack  is 
released.  This  protects  the  stacks  owned  by  application  programs  or  system  device  drivers 
from  overflowing  when  several  interrupts  occur  in  rapid  succession. 

The  STACKS  command  configures  the  number  and  size  of  internal  stacks  available  for 
interrupt  handling  and  thus  controls  the  number  of  interrupts  that  can  exist  only  partially 
processed  while  still  allowing  another  interrupt  to  occur. 

The  number  parameter  sets  the  number  of  internal  stacks  to  be  allocated;  number  must 
be  in  the  range  8  through  64.  The  size  parameter  is  the  number  of  bytes  allocated  per 
stack  frame;  size  must  be  in  the  range  32  through  512. 

If  too  many  interrupts  occur  too  quickly  and  the  pool  of  internal  stack  frames  is  exhausted, 
the  system  halts  with  the  message  Internal  Stack  Overflow.  Increasing  the  number 
parameter  in  the  STACKS  command  usually  corrects  the  problem. 

Example 

To  configure  10  stacks  of  256  bytes  each  for  use  by  interrupt  handlers,  insert  the  line 

STACKS=1 0,256 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Message 

Unrecognized  command  in  CONFIG.SYS 

An  invalid  number  was  specified  in  the  STACKS  command. 
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COPY  1.0  and  later 

Copy  File  or  Device  Internal 


Purpose 

Copies  one  or  more  files  from  one  disk,  directory,  or  filename  to  another.  Can  also  copy 
files  to  or  from  character  devices. 

Syntax 

COPY  source  [A]  [/B]  [+ source  [/A]  [/B] . . .  ]  [destination]  [A]  l/B]  [/V] 

\ 

where:  \ 

\ 

source  is  the  names  of  the  file(s)  to  be  copied,  optionally  preceded  by  a  drive 

and/or  path;  wildcard  characters  are  permitted  in  filenames.  The  source 
can  also  be  a  device. 

destination  is  the  location  and,  optionally,  the  name(s)  for  the  copied  file(s)  and  can 
be  preceded  by  a  drive;  wildcard  characters  are  permitted  in  the  filename. 
The  destination  can  also  be  a  device. 

A  indicates  that  the  previous  file  is  an  ASCII  text  file. 

/B  indicates  that  the  previous  file  is  a  binary  file. 

/V  performs  read-after-write  verification  of  destination  file(s). 

Description 

The  COPY  command  copies  one  or  more  source  files  to  one  or  more  destination  files. 
When  multiple  files  are  copied,  the  name  of  each  source  file  is  displayed  as  it  is  processed. 
The  COPY  command  can  also  be  used  to  send  the  contents  of  a  file  to  a  character  device 
or  to  copy  input  from  a  character  device  into  a  file. 

The  source  parameter  identifies  the  file  or  files  to  be  copied.  It  can  consist  of  any  combina¬ 
tion  of  drive,  path,  and  filename  or  it  can  be  a  device  name.  If  a  path  without  a  filename  is 
specified,  all  files  in  the  named  directory  are  copied.  Several  source  files  can  be  concate¬ 
nated  into  a  single  destination  file  by  placing  a  +  operator  between  their  names;  if  the 
source  filename  contains  a  wildcard  but  the  destination  name  does  not,  all  the  source  files 
are  concatenated  into  the  specified  destination. 

Warning:  When  multiple  source  files  are  concatenated  into  a  destination  file  with  the 
same  name  as  one  of  the  source  files,  that  filename  should  be  specified  as  the  first  source 
file.  Otherwise,  the  contents  of  the  source  file  will  be  destroyed  before  the  file  is  copied. 

When  a  device  is  specified  as  the  source,  it  is  usually  the  console  (CON),  for  copying  key¬ 
board  input  to  a  file  or  another  device.  Keyboard  input  is  terminated  by  pressing  Ctrl-Z  or 
F6  (on  IBM  PCs  or  compatibles)  and  then  the  Enter  key. 
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The  destination  parameter  also  can  consist  of  any  combination  of  drive,  path,  and  file¬ 
name  or  be  a  device  name.  Unless  the  source  files  are  being  renamed  as  part  of  the  opera¬ 
tion,  destination  is  usually  simply  a  drive  and/or  path  specifying  where  to  place  the 
copied  files.  If  no  destination  is  specified,  the  source  file  is  copied  to  a  file  with  the  same 
name  in  the  current  directory  of  the  default  disk  drive;  if  the  source  file  in  this  case  is  itself 
in  the  current  directory  of  the  current  drive,  an  error  message  is  displayed  and  the  copy 
operation  is  aborted.  If  files  are  being  concatenated  and  no  destination  is  specified,  the 
source  files  are  copied  sequentially  into  one  file  in  the  current  directory  with  the  same 
name  as  the  first  source  file.  If  the  first  source  file  already  exists,  the  second  file  and  any 
additional  specified  files  are  appended  sequentially  to  the  first  source  file. 

The  A  and  /B  switches  control  the  manner  in  which  the  COPY  command  operates  on  a 
file.  Both  switches  affect  the  file  specification  immediately  preceding  them  and  any  subse¬ 
quent  file  specifications  in  the  command  until  another  A  or  /B  switch  is  encountered,  at 
which  point  the  new  A  or  /B  switch  takes  effect  for  the  file  immediately  preceding  it  and 
for  any  subsequent  files. 

The  A  switch  indicates  that  a  file  is  an  ASCII  text  file.  When  the  A  switch  is  applied  to  a 
source  file,  the  file  is  copied  up  to,  but  not  including,  the  first  Control-Z  (^Z)  character  in 
the  file.  When  the  A  switch  is  applied  to  a  destination  file,  a  Control-Z  character  is  ap¬ 
pended  by  the  COPY  command  as  the  last  character  of  the  new  file. 

The  /B  switch  indicates  a  binary  file.  When  /B  is  applied  to  a  source  file,  the  exact  number 
of  bytes  in  the  original  file  are  copied  without  regard  to  Control-Z  or  any  other  control 
characters.  When  the  /B  switch  is  applied  to  a  destination  file,  no  Control-Z  character  is 
appended  to  the  newly  created  file. 

The  default  values  for  the  A  and  /B  switches  for  file-to-file  copies  are  A  when  source  files 
are  being  concatenated  and  /B  otherwise.  When  a  file  is  being  copied  to  or  from  a  charac¬ 
ter  device,  the  /A  switch  is  the  default. 

The  /V  switch  causes  a  read-after-write  verification  of  each  block  of  the  destination  file.  Its 
effect  is  equivalent  to  that  of  the  VERIFY  ON  command.  No  comparison  is  made  between 
the  source  and  destination  files — the  /V  switch  simply  causes  MS-DOS  to  verify  that  the 
destination  file  has  been  written  correctly. 

Examples 

To  copy  the  file  REPORT.TXT  from  the  root  directory  of  the  disk  in  drive  B  to  a  file  named 
FINAL.RPT  in  the  \WP\DOCS  directory  on  the  current  drive,  type 

C>COPY  B:\REPORT.TXT  \WP\DOCS\FINAL . RPT  <Enter> 

To  make  a  copy  of  the  file  A:\V2\SOURCE\MENUMGR.C  in  the  current  directory  of  the 
current  drive,  type 

C>COPY  A:\V2\S0URCE\MENUMGR.C  <Enter> 
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To  copy  all  files  with  the  extension  .DOC  in  the  current  directory  of  the  disk  in  drive  A  to 
files  with  the  same  filenames  but  a  .TXT  extension  in  the  current  directory  of  the  current 
drive,  type 

C>COPY  A:*. DOC  *.TXT  <Enter> 

To  combine  the  files  PROLOG.C,  MENUMGR.C,  and  EPILOG.C  in  the  current  directory  of 
the  current  drive  into  a  single  file  named  VISUAL.C  in  the  current  directory  of  the  current 
drive,  type 

OCOPY  PROLOG. C+MENUMGR.C+EP I LOG. C  VISUAL.C  <Enter> 

To  append  the  files  MENUMGR.C  and  EPILOG.C  to  an  existing  file  named  PROLOG.C  in 
the  current  directory  of  the  current  drive,  type 

C>COPY  PROLOG. C+MENUMGR.C+EP I LOG. C  <Enter> 

To  copy  the  file  MENIJMGR.MAP  in  the  current  directory  of  the  current  drive  to  the  system 
printer,  type 

OCOPY  MENUMGR.MAP  PRN  <Enter> 

To  copy  input  from  the  keyboard  (CON)  to  a  file  named  MENU.BAT  in  the  current  direc¬ 
tory  of  the  current  drive,  type 

OCOPY  CON  MENU.BAT  <Enter> 

Text  subsequently  entered  from  the  keyboard  is  placed  into  the  file  MENU.BAT  until  a 
Ctrl-Z  or  F6  is  pressed. 

To  copy  all  files  in  the  \ MEMOS  directory  on  the  current  drive  to  the  \ ARCHIVE  directory 
on  the  disk  in  drive  B,  type 

OCOPY  \MEMOS\*.*  B:\ARCHIVE  <Enter> 

or 

OCOPY  \MEMOS  B:\ARCHIVE  <Enter> 

Messages 

If  File(s)  copied 

This  informational  message  is  displayed  at  the  completion  of  a  COPY  command  and  indi¬ 
cates  the  total  number  of  source  files  processed. 

Cannot  do  binary  reads  from  a  device 

The  COPY  command  specified  a  copy  from  a  character  device  in  binary  mode.  Reenter 
the  command  without  a  /B  switch. 

Content  of  destination  lost  before  copy 

One  of  the  source  files  specified  as  a  destination  file  was  overwritten  prior  to  completion 
of  the  copy.  When  the  destination  name  is  the  same  as  one  of  the  source  names,  that  file 
should  be  specified  as  the  first  source  file. 
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File  cannot  be  copied  onto  itself 

The  source  directory  and  filename  of  a  file  being  copied  are  the  same  as  the  destination 
directory  and  filename. 

File  not  found 

A  file  specified  in  the  COPY  command  is  invalid  or  does  not  exist. 

Invalid  directory 

A  directory  specified  in  the  COPY  command  is  invalid  or  does  not  exist. 


Section  III:  User  Commands 


809 


CTTY 


CTTY  2.0  and  later 

Assign  Standard  Input/Output  Device  Internal 


Purpose 

Specifies  the  character  device  to  be  used  as  standard  input  and  output. 

Syntax 

CTTY  device 
where: 

device  is  the  logical  character-device  name. 

Description 

MS-DOS  ordinarily  uses  the  computer’s  built-in  keyboard  and  screen  (CON)  as  standard 
input  and  output.  The  CTTY  command  allows  another  character  device  to  be  assigned 
instead. 

CTTY  allows  MS-DOS  commands  to  be  issued  from  a  terminal  attached  to  the  computer’s 
serial  port  or  from  another  custom  device  with  a  screen  and  keyboard.  Although  PRN  and 
NUL  are  valid  MS-DOS  device  names,  they  should  not  be  used  with  this  command,  as  they 
have  no  input  capability. 

Programs  that  do  not  use  MS-DOS  function  calls  to  perform  their  input  and  output  will  not 
be  affected  by  the  CTTY  command.  Microsoft  BASIC  is  an  example  of  such  a  program. 

Examples 

To  use  a  terminal  connected  to  the  serial  port  as  standard  input  and  output  for  programs, 
type 

C>CTTY  AUX  <Enter> 

To  reinstate  the  normal  keyboard  and  video  display  (CON)  as  standard  input  and  output 
for  programs,  type 

C>CTTY  CON  <Enter> 

on  the  currently  assigned  console  device. 

Message 

Invalid  device 

The  specified  device  is  not  a  legal  character-device  name  or  does  not  exist  in  the  system. 
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DATE 


1.0  and  later 


Set  Date 


Internal 


Purpose 

Sets  or  displays  the  system  date. 

Syntax 

DATE  mm-dd-yy 
or 

DATE  mm/dd/yy 
or 

DATE  mm.dd.yy  (versions  3.0  and  later) 
where: 

mm  is  the  month  (1- 12). 

dd  is  the  day  (1-31). 

yy  is  the  year  (80-99  or  1980-1999;  80-79  or  1980-2079  with  versions  3.0  and 

later). 

Description 

All  computers  that  run  MS-DOS  have  as  part  of  their  hardware  configuration  a  timer,  or 
clock,  that  maintains  the  current  system  date  and  time.  Among  other  uses,  the  current  date 
and  time  are  inserted  into  a  file’s  directory  entry  when  the  file  is  created  or  modified. 

The  DATE  command  allows  the  user  to  display  or  modify  the  current  date  that  is  being 
maintained  by  the  system’s  real-time  clock.  The  command  is  executed  automatically  by 
MS-DOS  when  the  system  is  initialized,  unless  there  is  an  AUTOEXEC.BAT  file  on  the  sys¬ 
tem  disk,  in  which  case  DATE  is  executed  only  if  it  is  included  in  the  file. 

A  date  entered  using  the  DATE  command  does  not  permanently  change  the  system  date; 
the  newly  entered  date  will  be  lost  when  the  system  is  turned  off  or  reset.  On  IBM  PC/ATs 
and  compatibles,  which  have  a  built-in  battery-backed  clock/calendar,  the  system  setup 
program  (found  on  the  Diagnostics  for  IBM  Personal  Computer  AT  disk  or  equivalent)  must 
be  used  to  permanently  alter  the  date  stored  in  the  machine.  On  IBM  PCs,  PC/XTs,  and 
compatibles  equipped  with  add-on  cards  containing  battery-backed  clock/calendar  cir¬ 
cuitry,  it  is  generally  necessary  to  run  a  time/date  installation  program  (included  with 
the  card)  when  the  system  is  turned  on  to  set  the  system  date  and  time  from  the  clock/ 
calendar  on  the  card.  The  DATE  command  usually  has  no  effect  on  these  card-mounted 
clock/calendars. 
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The  order  of  the  day,  month,  and  year  in  the  DATE  command  depends  on  the  country 
code,  which  is  set  with  the  COUNTRY  command  in  the  CONFIG.SYS  file.  The  format 
shown  here  is  for  the  USA. 

Examples 

To  set  the  system  date  to  October  15, 1987,  type 

ODATE  10-15-87  <Enter> 

or 

ODATE  10/15/87  <Enter> 

or 

ODATE  10.15.87  <Enter> 

To  display  the  current  system  date,  type 

ODATE  <Enter> 

and  MS-DOS  will  respond  in  the  form 

Current  date  is  Thu  10-15-1987 
Enter  new  date  (mm-dd-yy) : 

To  leave  the  date  unchanged,  press  the  Enter  key. 

Messages 

Current  date  is  day  mm-dd-yyyy 
Enter  new  date  (mm-dd-yy): 

This  informational  message  and  prompt  are  displayed  when  MS-DOS  is  started  and  there 
is  no  AUTOEXEC.BAT  file  on  the  system  disk,  when  the  DATE  command  is  entered  alone, 
or  when  the  DATE  command  is  included  in  the  AUTOEXEC.BAT  file. 

Invalid  date 

Enter  new  date  (mm-dd-yy): 

The  date  entered  in  the  command  line  or  in  response  to  the  prompt  from  the  DATE  com¬ 
mand  was  not  formatted  properly  or  was  invalid. 
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DEL  or  ERASE  1.0  and  later 

Delete  File  internal 


Purpose 

Deletes  a  file  or  set  of  files.  DEL  and  ERASE  are  synonymous. 

Syntax 

DEL  [drive\[path\fileruime 
or 

ERASE  [drive][path]filename 
where: 

filename  is  the  name  of  the  file(s)  to  be  deleted,  optionally  preceded  by  a  drive  and/or 
path;  wildcard  characters  are  permitted  in  the  filename. 

Description 

The  DEL  command  marks  the  directory  entry  for  the  specified  file  as  deleted  and  frees  the 
disk  sectors  occupied  by  the  file.  If  the  command  line  ends  with  *.»  or  a  directory  name 
(including  the  special  directory  names .  and MS-DOS  prompts  the  user  for  confirma¬ 
tion  before  deleting  all  the  files  in  the  current  or  specified  directory.  Note  that  in  the  case 
of  a  directory  name,  the  directory  itself  is  not  removed;  only  the  files  within  it  are  deleted. 

Warning:  If  the  filename  specification  b^ins  with  an  •  wildcard  and  the  extension  is 
also  *  (for  example,  *xyz.*),  DEL  interprets  the  specification  as  *.•  and  prompts  the  user  for 
confirmation  before  deleting  all  files  from  the  current  or  specified  directory. 

Examples 

To  delete  the  file  HELLO.C  from  the  current  directory  on  the  current  drive,  type 

ODEL  HELLO.C  <Enter> 

To  delete  all  files  with  the  extension  .OBJ  from  the  \SOURCE  directory  on  the  disk  in  drive 
D,  type 

ODEL  D:\SOURCE\* .OBJ  <Enter> 

To  delete  all  files  from  the  current  directory  on  the  current  drive,  type 

ODEL  *  .  *  <Enter> 

or 

ODEL  .  <Enter> 

In  this  case,  MS-DOS  will  prompt  for  confirmation  that  all  files  should  be  deleted. 
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To  delete  all  files  from  the  directory  \WORD\ LETTERS  on  the  current  drive,  type 

C>DEL  \WORD\LETTERS  <Enter> 

Again,  MS-DOS  will  prompt  for  confirmation  that  all  files  should  be  deleted. 

Messages 

Access  denied 

The  specified  file  is  read-only.  Use  the  ATTRIB  command  with  the  -R  switch  to  remove 
the  file’s  read-only  status. 

Are  you  sure  (Y/N)? 

This  message  prompts  the  user  for  confirmation  if  the  command  would  delete  all  files  in 
a  directory  (if  the  command  line  ends  with  a  directory  name  or  ♦.*).  Respond  with  V  to 
delete  all  files  in  the  directory;  respond  with  N  to  terminate  the  command. 

File  not  found 

The  filename  in  the  command  is  invalid  or  the  file  does  not  exist  in  the  specified  directory. 

Invalid  directory 

One  of  the  directories  named  in  the  file  specification  is  invalid  or  does  not  exist. 

Invalid  drive  specification 

The  drive  code  in  the  file  specification  is  invalid  or  the  named  drive  does  not  exist  in  the 
system. 
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Display  Directory 


1.0  and  later 
Internal 


Purpose 

Displays  a  list  of  a  directory’s  files  and  subdirectories. 

Syntax 

DIR  [drive][patM.filename]  [/P]  [/W] 
where: 

filename  is  the  name  of  the  file,  optionally  preceded  by  a  drive  and/or  path,  whose 
directory  entry  is  to  be  displayed;  wildcard  characters  are  permitted. 

/P  causes  a  pause  after  each  screen  page  of  display. 

/W  causes  a  wide  display  of  filenames  formatted  five  across. 

Description 

The  DIR  command  displays  information  about  the  files  in  a  directory.  It  also  displays  infor¬ 
mation  about  the  volume  name  of  the  disk  that  contains  the  directory,  the  total  number  of 
files  and  subdirectories  in  the  directory,  and  the  amount  of  free  space  remaining  on  the 
disk. 

The  normal  format  of  the  DIR  command’s  output  is 


Volume  in  drive  C  is  HARDDISK 
Directory  of  C:\ASM 


. 

<DIR> 

9-19-85 

7;09p, 

<DIR> 

9-19-85 

7:09p 

LIB 

<DIR> 

9-17-86 

11  ;31p 

SOURCE 

<DIR> 

9-17-86 

11  :31p 

AT86 

EXE 

41146 

5-13-85 

5:18p 

CREF 

EXE 

15028 

10-16-85 

4:00a 

DEBUG 

COM 

15552 

3-07-85 

1  :43p 

EXE2BIN 

EXE 

2816 

3-07-85 

1  :43p 

EXEMOD 

EXE 

11034 

10-16-85 

4:00a 

EXEPACK 

EXE 

10848 

10-16-85 

4:00a 

LIB 

EXE 

28716 

10-16-85 

4:00a 

LINK 

EXE 

43988 

10-16-85 

4:00a 

MAKE 

EXE 

24300 

10-16-85 

4:00a 

MAPSYM 

EXE 

18026 

10-16-85 

4:00a 

MASM 

EXE 

85566 

10-16-85 

4:00a 

SYMDEB 

EXE 

37021 

10-16-85 

4:00a 

T86 

EXE 

49024 

12-06-84 

4:03p 

17  File(s)  4022272  bytes  free 


The  first  line  shows  the  volume  label  of  the  disk  that  contains  the  directory  being  dis¬ 
played;  the  second  line  gives  the  full  pathname  of  the  directory.  The  subsequent  lines  are 
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the  names  of  the  files  and  subdirectories  within  the  current  or  specified  directory.  Each 
entry  includes  the  time  and  date  the  file  or  subdirectory  was  created  or  last  modified. 

Files  are  shown  with  their  exact  size  in  bytes;  directories  are  shown  with  the  symbol 
<DIR>.  If  the  directory  being  listed  is  not  the  root  directory  of  the  disk,  it  always  contains 
the  two  special  directory  entries .  and which  are  aliases  for  the  current  directory  and  the 
parent  directory,  respectively.  These  aliases  are  included  in  the  total  file  count  in  the  last 
line  of  the  display. 

Subsets  of  the  files  and  subdirectories  in  the  current  or  specified  directory  of  the  current 
or  specified  drive  can  be  listed  by  including  a  filename  with  wildcards  in  the  command 
line.  For  example,  the  filename  *.000  will  cause  DIR  to  list  only  the  files  with  a  .DOC 
extension. 

If  the  command  line  ends  with  a  drive  or  path,  DIR  automatically  appends  an  ♦.♦,  causing 
all  files  and  subdirectories  in  the  current  or  specified  directory  of  the  current  or  specified 
drive  to  be  listed.  If  a  filename  is  included  but  no  extension  is  given,  DIR  appends  a  .*  to 
the  filename,  causing  all  files  with  that  name  to  be  listed,  regardless  of  their  extension.  If  a 
filename  ending  with  a .  is  included,  nothing  is  appended  and  all  matching  subdirectories 
and  filenames  without  extensions  are  listed. 

The  /P  switch  causes  a  pause  in  the  display  after  each  screen  page  (23  lines  plus  a  mes¬ 
sage).  The  listing  resumes  when  the  user  presses  a  key. 

The  /  W  switch  causes  the  list  to  be  in  a  more  compact  format  by  omitting  size  and  date/ 
time  information  and  by  displaying  the  filenames  five  across: 

Volume  in  drive  C  is  HARDDISK 
Directory  of  C:\ASM 

LIB  SOURCE 

CREF  EXE  DEBUG  COM  EXE2BIN  EXE  EXEMOD  EXE 

LIB  EXE  LINK  EXE  MAKE  EXE  MAPSYM  EXE 

SYMDEB  EXE  T86  EXE 

17  File(s)  4022272  bytes  free 

When  the  /  W  form  of  the  listing  is  displayed,  subdirectories  are  not  easily  distinguished 
from  files  because  the  <DIR>  symbol  is  not  shown. 

Examples 

To  list  all  files  in  the  current  directory  on  the  current  drive,  type 

ODIR  <Enter> 

To  list  all  files  in  the  current  directory  on  the  disk  in  drive  B,  type 

ODIR  B:  <Enter> 

or 

ODIR  B:*.*  <Enter> 


AT 8 6  EXE 
EXEPACK  EXE 
MASM  EXE 
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To  list  all  files  in  the  directory  \  SOURCE  on  the  current  drive,  type 

ODIR  \SOURCE  <Enter> 

or 

ODIR  \SOURCE\*.*  <Enter> 

To  list  all  files  with  the  extension  .OBJ  in  the  \LIB  directory  on  the  disk  in  drive  D,  type 

ODIR  D:\LIB\*.OBJ  <Enter> 

To  list  all  files  in  the  parent  directory  of  the  current  directory  on  the  current  drive,  type 

ODIR  .  .  <Enter> 

To  list  all  files  in  the  current  directory  on  the  current  drive,  sorted  by  filename  and  exten¬ 
sion,  type 

ODIR  !  SORT  <Enter> 

To  list  all  files  in  the  current  directory  on  the  current  drive,  sorted  by  extension,  type 

ODIR  !  SORT  /  +  10  <Enter> 

The  /+10  instructs  SORT  to  sort  the  directory  entries  starting  at  the  tenth  column,  which  is 
the  first  column  of  the  filename  extension. 

To  list  the  subdirectories  and  files  without  extensions  in  the  current  directory,  type 

ODIR  * .  <Enter> 

To  print  the  directory  on  an  attached  printer  instead  of  displaying  it  on  the  screen,  type 

ODIR  >  PRN  <Enter> 

To  make  a  copy  of  the  directory  in  a  file  called  FILES.TXT,  type 

ODIR  >  FILES.TXT  <Enter> 

Messages 

File  not  found 

A  filename  was  included  in  the  command  line  and  no  matching  files  were  found. 

Invalid  directory 

An  element  of  the  path  included  in  the  command  line  does  not  exist. 

Invalid  drive  specification 

The  specified  drive  is  invalid  or  is  not  present  in  the  system. 

Strike  a  key  when  ready. . . 

If  the  DIR  command  includes  the  /P  switch,  the  display  is  suspended  after  each  23  lines 
and  this  message  prompts  the  user  to  press  a  key  to  see  the  next  screenful  of  entries. 
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DISKCOMP  32 

Compare  Floppy  Disks  External 


Purpose 

Compares  two  entire  floppy  disks  on  a  sector-by-sector  basis  and  reports  any  differences. 
This  command  was  included  with  PC-DOS  beginning  with  version  1.0.  To  compare  indi¬ 
vidual  files,  see  USER  COMMANDS:  comp;  fc. 

Syntax 

DISKCOMP  [drivel]  [drive2]  [/I]  1/8] 
where: 

drivel  is  the  drive  containing  the  first  disk  to  be  compared. 

drive2  is  the  drive  containing  the  second  disk  to  be  compared. 

/I  compares  only  the  first  sides  of  the  disks. 

/8  compares  only  the  first  eight  sectors  of  each  track. 

Description 

The  DISKCOMP  command  compares  the  physical  sectors  of  one  floppy  disk  with  those 
of  another.  The  drivel  and  drive2  parameters  designate  the  drives  holding  the  two  disks 
to  be  compared;  the  drives  should  always  be  of  the  same  type.  If  drive2  is  omitted, 
DISKCOMP  uses  the  current  drive.  If  both  drivel  and  drive2  are  omitted  or  are  identical, 
DISKCOMP  performs  the  comparison  using  a  single  drive,  prompting  the  user  to  swap 
disks  as  required. 

Ordinarily,  DISKCOMP  determines  the  disk  format  by  inspecting  the  disk  in  drivel.  The  /I 
and  /8  switches  override  this  check  so  that  only  one  side  of  the  disks  or  only  the  first  eight 
sectors  of  each  track  are  compared,  regardless  of  the  actual  format  of  the  disks. 

If  all  the  sectors  on  all  the  tracks  are  identical,  DISKCOMP  displays  the  message  Compare 
OK.  If  differences  are  found,  DISKCOMP  reports  them  by  issuing  a  message  that  includes 
the  numbers  of  the  track  and  disk  side  (read/write  head)  where  the  differences  occur. 
Because  DISKCOMP  works  at  the  level  of  the  disks’  physical  sectors  and  is  ignorant  of  the 
control  areas  and  file  structures  imposed  on  a  disk  by  MS-DOS,  it  also  reports  as  errors  bad 
sectors  that  were  marked  during  the  FORMAT  process. 

When  DISKCOMP  finishes  comparing  two  disks,  it  displays  a  prompt  that  allows  the  user 
to  choose  between  comparing  another  pair  of  disks  and  returning  to  the  MS-DOS  com¬ 
mand  level. 

DISKCOMP  cannot  be  used  with  a  network  drive  or  with  a  drive  created  or  affected  by  an 
ASSIGN,  JOIN,  or  SUBST  command,  nor  can  it  be  used  with  fixed  disks. 
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Return  Codes 

0  Compared  disks  were  identical. 

1  Differences  were  found  between  the  compared  disks. 

2  DISKCOMP  was  terminated  with  a  Control-C. 

3  Bad  sector  was  found  on  one  of  the  disks  being  compared. 

4  Initialization  error  was  encountered:  not  enough  memory,  syntax  error  in  command 
line,  or  invalid  drive  specified  in  command  line. 

Note:  Return  codes  are  not  present  in  the  PC-DOS  version  of  DISKCOMP. 

Examples 

To  compare  the  disk  in  drive  A  with  the  disk  in  drive  B,  type 

C>.DISKCOMP  A:  B:  <Enter> 

To  compare  two  disks  using  only  drive  A,  type 

C> DISKCOMP  A:  A:  <Enter> 

To  compare  only  the  first  side  of  the  disk  in  drive  A  with  the  first  side  of  the  disk  in  drive 
B,type 

ODISKCOMP  A:  B:  /I  <Enter> 

To  compare  only  the  first  eight  sectors  of  each  track  on  one  side  of  one  disk  with  the  first 
eight  sectors  of  each  track  on  one  side  of  another  disk  using  only  drive  A,  type 

C>DISKCOMP  A;  A:  /I  /8  <Enter> 

Messages 

Cannot  DISKCOMP  to  or  from 
an  ASSIGNed  or  SUBSTed  drive 

One  of  the  specified  drives  has  been  affected  by  an  ASSIGN  or  SUBST  command. 

Cannot  DISKCOMP  to  or  from 
a  network  drive 

One  of  the  specified  drives  is  a  network  device. 

Compare  another  diskette  (Y/N)  ? 

This  prompt  allows  comparison  of  another  pair  of  disks.  Respond  with  Y  to  cause 
DISKCOMP  to  prompt  for  insertion  of  the  next  pair  of  disks  to  be  compared;  respond  with 
N  to  exit  to  MS-DOS. 

Compare  error  on  side  n,  track n 

A  difference  was  detected  between  the  two  disks  being  compared. 

Compare  OK 

The  two  disks  being  compared  are  identical. 


Section  III:  User  Commands 


819 


DISKCOMP 


Compare  process  ended 

The  disk  comparison  was  terminated  as  the  result  of  a  fatal  error. 

Comparing  n  tracks, 

If  sectors  per  track,  n  side(s) 

This  informational  message  specifies  the  format  of  the  two  disks  being  compared. 

DEVICE  Support  Not  Present 

The  disk  drive  does  not  support  MS-DOS  3.2  device  control. 

Drive  JT  not  ready 

Make  sure  a  diskette  is  inserted  into 
the  drive  and  the  door  is  closed 

DISKCOMP  was  unable  to  read  the  disk  in  the  specified  drive. 

Drive  types  or  diskette  types 
not  compatible 

Single-sided  disks  cannot  be  compared  with  double-sided  disks,  nor  high-density  disks 
with  double-density  disks. 

FIRST  diskette  bad  or  incompatible 

DISKCOMP  is  unable  to  determine  the  format  of  the  first  disk. 

Incorrect  DOS  version 

The  version  of  DISKCOMP  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insert  diskette  with  directory  that  contains 
COMMAND.COM  in  drive X  and  strike  any  key  when  ready 

If  the  system  was  booted  from  a  floppy  disk  and  the  system  disk  was  then  removed  in 
order  to  use  DISKCOMP,  the  user  must  replace  the  system  disk  after  the  compare  opera¬ 
tion  is  complete. 

Insert  FIRST  diskette  in  drive  A*: 

Press  any  key  when  ready. . . 

This  message  prompts  the  user  to  insert  the  first  disk  of  a  pair  to  be  compared. 

Insert  SECOND  diskette  in  drive  X: 

Press  any  key  when  ready. . . 

This  message  prompts  the  user  to  insert  the  second  disk  of  a  pair  to  be  compared. 

Insufficient  memory 

The  available  system  memory  is  insufficient  to  load  and  execute  the  DISKCOMP  program. 

Invalid  drive  specification 
Specified  drive  does  not  exist 
or  is  non-removable 

One  of  the  drives  specified  in  the  command  line  is  invalid  or  does  not  exist. 
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Invalid  parameter 
Do  not  specifjr  filename(s) 

Command  format:  DISKCOMP  d:  d:  [/l][/8] 

A  syntax  error  was  detected  in  the  command  line,  usually  caused  by  an  incorrect  switch. 

SECOND  diskette  bad  or  incompatible 

The  second  disk  of  a  pair  to  be  compared  does  not  have  the  same  format  as  the  first  disk  or 
has  bad  sectors  preventing  DISKCOMP  from  determining  its  format. 

Unrecoverable  read  error  on  drived: 

The  disk  in  the  specified  drive  contains  an  unreadable  sector. 
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DISKCOPY  2.0  and  later 

Copy  Floppy  Disks  External 


Purpose 

Performs  a  sector-by-sector  copy  of  one  entire  floppy  disk  to  another  floppy  disk.  This 
command  was  included  with  PC-DOS  beginning  with  version  1.0.  To  copy  individual  files, 
see  USER  COMMANDS:  copy. 

Syntax 

DISKCOPY  [drivel]  [drive2]  [/I] 
where: 

driwl  is  the  drive  containing  the  disk  to  be  copied. 

drive2  is  the  drive  containing  the  disk  that  will  become  the  copy. 

/I  copies  only  the  first  side  of  the  disk  in  drivel  (MS-DOS  version  3.2). 

Description 

The  DISKCOPY  command  duplicates  a  floppy  disk,  performing  the  copy  on  a  physical 
sector-by-sector  basis.  The  drivel  parameter  specifies  the  location  of  the  disk  to  be  copied 
(the  source  disk).  The  drive2  parameter  specifies  the  location  of  the  disk  that  will  become 
the  copy  (the  destination  disk).  If  drive2  is  omitted,  the  current  drive  is  used  as  the  desti¬ 
nation  drive;  if  both  drivel  and  drive2  parameters  are  omitted  or  are  the  same,  DISKCOPY 
performs  the  copy  operation  using  a  single  drive,  prompting  the  user  to  swap  the  disks  as 
necessary. 

DISKCOPY  examines  the  destination  disk  before  writing  any  information  and  terminates 
with  an  error  message  if  it  does  not  have  the  same  format  as  the  source  disk.  If  the  destina¬ 
tion  disk  is  not  formatted,  DISKCOPY  formats  it  with  the  same  format  as  the  source  disk,  as 
part  of  the  DISKCOPY  operation. 

Note:  With  MS-DOS  versions  2.0  through  3.1,  the  destination  disk  must  be  formatted  using 
the  FORMAT  command  before  DISKCOPY  can  be  used.  All  PC-DOS  versions  of 
DISKCOPY  will  automatically  format  the  destination  disk,  if  necessary. 

When  DISKCOPY  finishes  copying  a  disk,  it  displays  a  prompt  that  allows  the  user  to 
choose  between  copying  another  disk  and  returning  to  the  MS-DOS  command  level. 

Because  DISKCOPY  creates  an  exact  duplicate  of  the  source  disk,  any  file  fragmentation 
present  on  the  source  disk  is  also  present  on  the  destination  disk  after  the  DISKCOPY 
process  is  complete.  To  eliminate  fragmentation  of  the  source  files,  they  should  be  copied 
to  the  destination  disk  individually  using  COPY  or  XCOPY. 

The  DISKCOPY  command  cannot  be  used  with  a  network  drive  or  with  a  drive  created  or 
affected  by  an  ASSIGN,  JOIN,  or  SUBST  command,  nor  can  it  be  used  with  fixed  disks. 
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Return  Codes 

0  Disk  was  copied  successfully. 

1  Nonfatal  but  unrecoverable  read  or  write  error  occurred  (no  Interrupt  24H  generated). 

2  DISKCOPY  was  terminated  with  a  Control-C. 

3  Fatal  error  was  encountered:  unreadable  source  disk  or  unformattable  destination 
disk. 

4  Initialization  error  was  encountered:  not  enough  memory,  syntax  error  in  command 
line,  or  invalid  drive  specified  in  command  line. 

Note:  Return  codes  are  not  present  in  the  PC-DOS  version  of  DISKCOPY. 

Examples 

To  copy  the  contents  of  the  disk  in  drive  A  to  the  disk  in  drive  B,  type 

ODISKCOPY  A:  B:  <Enter> 

To  copy  the  contents  of  the  disk  in  drive  A  using  only  one  drive,  type 

ODISKCOPY  A:  A:  <Enter> 

To  copy  only  the  first  side  of  the  disk  in  drive  A  to  the  first  side  of  the  disk  in  drive  B,  type 

ODISKCOPY  A:  B:  /I  <Enter> 

Messages 

Cannot  DISKCOPY  to  or  from 
an  ASSIGNed  or  SUBSTed  drive 

One  of  the  specified  drives  has  been  affected  by  an  ASSIGN  or  SUBST  command. 

Cannot  DISKCOPY  to  or  from 
a  network  drive 

One  of  the  specified  drives  is  a  network  device. 

Copy  another  diskette  (Y/N)  ? 

This  prompt  allows  copying  of  another  disk.  Respond  with  Y  to  cause  DISKCOPY  to 
prompt  for  insertion  of  the  next  set  of  disks;  respond  with  N  to  exit  to  MS-DOS. 

Copying  If  tracks 
If  sectors  per  track,  n  side(s) 

This  informational  message  specifies  the  format  of  the  source  disk  being  copied. 

Copy  process  ended 

The  DISKCOPY  process  has  been  successfully  completed  or  has  been  terminated  by  a  fatal 
error.  In  the  latter  case,  this  message  is  preceded  by  another  message  explaining  the  error. 

DEVICE  Support  Not  Present 

The  disk  drive  does  not  support  MS-DOS  version  3.2  device  control. 
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Disk  error  while  reading  drived: 

Abort,  Retry,  Ignore? 

A  bad  sector  was  detected  on  the  source  disk.  This  does  not  necessarily  invalidate  the  disk 
copy;  the  bad  sector  may  originally  have  been  detected  and  flagged  by  the  FORMAT  pro¬ 
gram  and  therefore  not  included  in  any  file.  One  solution  is  to  copy  the  files  individually 
using  the  COPY  command. 

Drived:  not  ready 

Make  sure  a  diskette  is  inserted  into 

the  drive  and  the  door  is  closed 

DISKCOPY  was  unable  to  read  the  disk  in  the  specified  drive. 

Drive  types  or  diskette  types 
not  compatible 

Single-sided  disks  cannot  be  copied  to  or  from  double-sided  disks,  nor  high-density  disks 
to  or  from  double-density  disks. 

Formatting  while  copying 

The  destination  disk  was  not  previously  formatted.  It  is  given  the  same  format  as  the 
source  disk  as  part  of  the  DISKCOPY  operation  (MS-DOS  version  3.2). 

Incorrect  DOS  version 

The  version  of  DISKCOPY  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insert  diskette  with  directory  that  contains 
COMMAND.COM  in  driveX  and  strike  any  key  when  ready 

If  the  system  was  booted  from  a  floppy  disk  and  the  system  disk  was  then  removed  in 
order  to  use  DISKCOPY,  the  user  must  replace  the  system  disk  after  the  copy  operation  is 
complete. 

Insert  SOURCE  diskette  in  drive  JT: 

Press  any  key  when  ready. . . 

or 

Insert  TARGET  diskette  in  driveX: 

Press  any  key  when  ready. . . 

These  messages  prompt  the  user  to  insert  the  source  and  destination  disks  before  begin¬ 
ning  the  copy  operation. 

Insufficient  memory 

The  available  system  memory  is  insufficient  to  load  and  execute  the  DISKCOPY  program. 

Invalid  drive  specification 
Specified  drive  does  not  exist, 
or  is  non-removable 

One  of  the  drives  specified  in  the  command  line  is  invalid  or  does  not  exist.  A  fixed  disk 
cannot  be  the  source  or  destination  disk  for  a  DISKCOPY  operation. 
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Invalid  parameter 
Do  not  specify  f ilename(s) 

Command  Format:  DISKCOPY  d:  d:  [/I] 

A  syntax  error  was  detected  in  the  command  line,  usually  caused  by  an  incorrect  switch  or 
by  the  use  of  a  filename  instead  of  (or  in  addition  to)  a  disk  drive. 

SOURCE  diskette  bad  or  incompatible 

or 

TARGET  diskette  bad  or  incompatible 

The  source  disk  could  not  be  read  or  the  destination  disk  could  not  be  formatted. 

Target  diskette  is  write  protected 

The  destination  disk  has  a  write-protect  tab  on  it. 

Target  diskette  may  be  unusable 

Unrecoverable  read  or  write  errors  were  encountered  while  copying  the  source  disk  to  the 
destination  disk.  The  newly  copied  disk  may  not  be  an  accurate  copy. 

Unrecoverable  read  error  on  drived: 
side  If,  track  If 

or 

Unrecoverable  write  error  on  drived; 
side  If,  track  If 

The  disk  in  the  specified  drive  contained  a  sector  that  could  not  be  successfully  read  or 
written. 
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DRIVER.SYS  32 

Configurable  External-Disk-Drive  Driver  External 


Purpose 

Installs  and  configures  external  disk  drives  or  assigns  logical  drive  letters  to  existing 
floppy-disk  drives. 

Syntax 

DEVICE=DRIVER.SYS  /D:  n  [/C]  [/F:  n]  [/H:  n]  [/N]  [/S:  n]  [/T:  n] 
where: 

/D:  n  is  the  drive  number  (0-127  for  floppy  disks,  128-255  for  fixed  disks)  and  must 

always  be  the  first  switch  in  the  command  line. 

/C  specifies  that  door-lock-status  support  is  available. 

/F:  n  is  the  form-factor  index  for  the  device  (default  =  2): 

0  320/360  KB 

1  1.2  MB 

2  720  KB 

3  8"  single-density  floppy  disk 

4  8"  double-density  floppy  disk 

5  fixed  disk 

6  magnetic-tape  drive 

7  other 

/H:  n  is  the  number  of  heads  supported  by  the  disk  drive  (1-99). 

/N  specifies  a  nonremovable  block  device. 

/S:  n  is  the  number  of  sectors  per  track  (1-40). 

/T:  w  is  the  tracks  per  read/write  head  (1-999). 

Description 

when  the  computer  is  turned  on  or  restarted,  MS-DOS  assigns  numbers  to  all  existing  in¬ 
ternal  disk  drives.  The  DRIVER.SYS  file — an  installable,  configurable  block-device  driver 
for  external  disk  drives  and  other  mass-storage  devices — allows  installation  of  peripheral 
devices  that  are  not  supported  by  the  resident  drivers  in  the  MS-DOS  BIOS  module. 
DRIVER.SYS  can  also  assign  a  logical  drive  letter  to  an  existing  disk  drive,  thus  giving  the 
device  two  drive  letters.  (This  allows  such  activities  as  copying  files  between  like  media — 
for  example,  copying  files  from  one  1.2  MB  5.25-inch  disk  to  another — using  the  same 
drive.) 
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The  /D:  n  switch  assigns  a  unit  number  to  the  additional  disk  drive  or  specifies  the  number 
of  the  existing  disk  drive  that  is  to  be  assigned  a  logical  drive  letter.  (Floppy-disk  unit  num¬ 
bers  begin  at  0;  fixed-disk  numbers  begin  at  80H.)  For  example,  if  the  system  contains  two 
floppy-disk  drives  (0  and  1),  an  external  floppy-disk  drive  requiring  DRIVER.SYS  would 
be  assigned  the  value  2;  MS-DOS  would  then  assign  that  drive  the  next  available  drive  let¬ 
ter.  If  the  number  used  with  the  /D:  w  switch  references  an  existing  drive  (for  example,  0, 
the  first  floppy-disk  drive),  MS-DOS  assigns  the  drive  the  next  available  drive  letter,  allow¬ 
ing  the  one  drive  unit  to  be  referenced  by  two  drive  letters.  The  /D:  n  switch  is  not  op¬ 
tional  and  must  precede  all  other  switches  in  the  command  line. 

The  /C,  /F: «,  and  /N  switches  describe  characteristics  of  the  disk  drive  that  is  being  se¬ 
lected  for  use  with  DRIVER.SYS.  The  /C  switch  is  included  only  if  the  device  has  a  status 
line  indicating  whether  the  disk  in  the  drive  has  been  changed.  (This  information  is  used 
by  the  driver  to  optimize  disk  accesses  to  the  directory  and  file  allocation  table.)  If  the 
device  does  not  have  a  status  line,  /C  will  have  no  effect.  The  /F:  n  option  describes  the 
form-factor  index  used  by  the  device.  The  permissible  values  for  n  are  given  in  the  pre¬ 
ceding  table;  the  default  type  is  a  720  KB  disk.  The  /N  switch  indicates  that  the  block 
device  is  nonremovable.  Access  to  such  devices  is  more  efficient  than  access  to  removable 
media  because  MS-DOS  can  eliminate  calls  to  the  driver  for  a  media-change  check. 

The  /H: «,  /S: «,  and  /T:  w  switches  describe  the  physical  layout  of  the  recording  medium. 
/H:  n  specifies  the  number  of  recording  surfaces,  or  read-write  heads,  supported  by  the 
drive  (1-99).  /S:  n  is  the  number  of  sectors  per  track  (1-40)  and  /T:  n  is  the  tracks  per  side 
(1-999).  (The  total  number  of  physical  sectors  on  a  given  disk  is  found  by  multiplying  the 
number  of  heads  by  the  tracks  per  side  and  the  sectors  per  track.) 

Note:  The  values  used  with  these  switches  must  be  supported  by  the  device  being  in¬ 
stalled.  If  DRI  VER.SYS  is  used  to  assign  a  logical  drive  letter  to  an  existing  physical  device, 
the  values  used  with  the  switches  must  be  identical  to  the  characteristics  imposed  by  the 
default  device  driver. 

Examples 

To  install  a  driver  for  an  external  720  KB  disk  drive  in  a  system  that  already  has  two 
5.25-inch  floppy-disk  drives,  insert  the  line 

DEVICE=DRIVER.SYS  /D:02 

into  the  CONFIG.SYS  file  and  restart  the  system. 

Assume  that  an  IBM  PC/AT  or  compatible  has  three  disk  drives  installed:  Drive  A  is  a  1.2 
MB  5.25-inch  floppy-disk  drive;  drive  B  is  a  360  KB  5.25-inch  floppy-disk  drive;  drive  C  is 
a  30  MB  fixed-disk  drive.  To  assign  the  logical  drive  letter  D  to  the  existing  drive  A,  effec¬ 
tively  giving  the  one  drive  two  drive  letters,  insert  the  line 

DEVICE=DRIVER.SYS  /D:0  /F:1  /H:2  /S:15  /T:80  /C 

into  the  CONFIG.SYS  file  and  restart  the  system. 
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Messages 

Bad  or  missing  DRIVER.SYS 

The  file  DRIVER.SYS  could  not  be  found  in  the  root  or  specified  directory  or  has  been 
damaged. 

ERROR  -  Incorrect  DOS  version 

The  version  of  DRIVER.SYS  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

ERROR  -  No  drive  specified 

The  /D:  n  switch  was  not  included  in  the  command  line. 

Loaded  External  Disk  Driver  for  Drive  JIT 

The  device  driver  has  been  successfully  installed  and  this  message  informs  the  user  of  the 
drive  letter  assigned  to  the  device. 

Sector  size  too  large  in  file  DRl VER.SYS 

DRI  VER.SYS  uses  a  sector  size  that  is  larger  than  the  sector  size  used  by  any  of  the  system’s 
default  disk  drivers.  The  driver  cannot  be  used  because  MS-DOS’s  internal  disk  buffers  will 
not  be  large  enough  to  hold  a  sector  read  from  the  device. 
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1.0  and  later 
External 


Purpose 

Creates  and  changes  ASCII  text  files. 

Syntax 

EDLIN  [dr ive{\[paM  filename  [/B] 
where: 

filename  is  the  name  of  an  ASCII  text  file  to  be  created  or  edited,  optionally  preceded 
by  a  drive  and/or  path. 

/B  causes  logical  end-of-file  marks  within  the  file  to  be  ignored  (versions  2.0  and 

later). 

Description 

The  EDLIN  program  is  a  simple  line-oriented  editor  that  can  be  used  to  create  or  maintain 
short  text  files.  The  user  references  and  edits  text  by  line  number;  EDLIN  displays  these 
numbers  for  convenience  but  they  do  not  become  part  of  the  file.  Each  line  of  the  file 
being  edited  can  be  a  maximum  of  253  characters. 

The  filename  parameter  specifies  a  plain  ASCII  text  file;  if  the  file  does  not  already  exist, 
EDLIN  creates  it.  (EDLIN  cannot  be  used  on  most  files  created  by  word-processing  pro¬ 
grams  because  such  document  files  have  embedded  formatting  codes  and  other  format¬ 
ting  information  that  EDLIN  cannot  interpret.)  EDLIN  does  not  assume  any  extensions;  the 
user  must  type  the  complete  filename.  (EDLIN  does  not  permit  editing  of  a  .BAK  file.) 

If  filename  is  a  previously  existing  text  file,  EDLIN  loads  lines  from  the  file  into  memory 
until  the  editing  buffer  is  75  percent  full  or  until  a  logical  end-of-file  mark  or  the  physical 
end  of  the  file  is  reached.  The  /B  switch  forces  EDLIN  to  ignore  any  logical  end-of-file 
marks  (lAH,  or  Control-Z)  the  file  may  contain.  If  the  file  is  too  large  for  the  edit  buffer,  the 
Write  Lines  to  Disk  (W)  and  Append  Lines  from  Disk  (A)  commands  are  used  during  the 
edit  session  to  process  the  remaining  portions  of  the  file. 

Once  the  file  is  created  or  loaded  into  the  editing  buffer,  EDLIN  displays  its  asterisk 
prompt  (♦)  and  the  user  can  begin  entering  editing  commands. 

EDLIN  commands  consist  of  a  single  character,  in  either  uppercase  or  lowercase,  usually 
preceded  by  one  or  more  line  numbers.  More  than  one  command  can  be  entered  on  a 
single  line  by  separating  the  commands  with  semicolons.  EDLIN  does  not  execute  a  com¬ 
mand  until  the  Enter  key  is  pressed. 
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The  EDLIN  commands  are 


Command 

Action 

linenumber 

Edit  line. 

A 

Append  lines  from  disk. 

C 

Copy  lines  (versions  2.0  and  later). 

D 

Delete  lines. 

E 

End  editing  session. 

I 

Insert  lines. 

L 

List  lines. 

M 

Move  lines  (versions  2.0  and  later). 

P 

Display  in  pages  (versions  2.0  and  later). 

Q 

Quit  without  saving  changes. 

R 

Replace  text. 

S 

Search  for  text. 

T 

Transfer  another  file  into  the  edit  buffer  (versions  2.0  and  later). 

W 

Write  lines  to  disk. 

Each  of  these  commands  is  discussed  in  detail  in  the  following  pages. 

All  EDLIN  commands  that  accept  a  line  number  or  range  of  line  numbers  can  also  recog¬ 
nize  the  following  symbolic  references: 

Symbol 

Meaning 

#  The  line  after  the  last  line  in  the  edit  buffer 

.  The  current  line 

+ w  or  -w  A  line  number  relative  to  the  current  line 

(for  example,  +5  =  five  lines  past  the  current  line) 

When  the  user  terminates  the  editing  session  with  the  E  command,  EDLIN  gives  the  new 
file  the  same  name  as  the  original  file  and  renames  the  original  (unchanged)  file  with  the 
extension  .BAK.  Any  previous  file  with  the  same  name  and  the  extension  .BAK  is  lost. 
When  the  user  terminates  the  editing  session  with  the  Q  command,  the  original  filename 
remains  unchanged. 

Example 

To  edit  the  file  AUTOEXEC.BAT  in  the  root  directory  of  the  current  drive,  type 

OEDLIN  \AUTOEXEC.BAT  <Enter> 

Messages 

Cannot  edit  .BAK  file — rename  file 

Files  with  the  extension  .BAK  cannot  be  edited  with  EDLIN.  Rename  the  file  or  copy  it  to  a 
file  with  the  same  name  but  a  different  extension. 
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End  of  input  file 

The  entire  file  has  been  read  into  memory. 

File  is  READ-ONLY 

Files  marked  with  the  read-only  attribute  cannot  be  edited.  Remove  the  read-only  attribute 
with  the  ATTRIB  command  or  copy  the  file  to  a  file  with  a  different  name. 

File  name  must  be  specified 

The  command  line  did  not  include  a  filename. 

File  not  found 

The  file  named  in  the  command  line  could  not  be  found  or  does  not  exist. 

Incorrect  DOS  version 

The  version  of  EDLIN  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insufficient  memory 

Not  enough  memory  is  available  to  carry  out  the  requested  command. 

Invalid  drive  or  file  name 

The  command  line  included  a  drive  that  is  invalid  or  does  not  exist  in  the  system  or  the 
filename  is  not  valid. 

Invalid  Parameter 

The  command  line  contained  an  illegal  switch  or  other  invalid  parameter. 

New  file 

The  file  named  in  the  command  line  did  not  previously  exist.  The  file  is  created  and  the 
edit  buffer  is  emptied. 

Read  error  in:  filename 

MS-DOS  was  unable  to  read  the  entire  file.  Run  CHKDSK  to  determine  whether  the  file  or 
disk  has  been  damaged. 
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EDLIN:  linenumber 


EDLIN:  linenumber  1.0  and  later 

Edit  Line 


Purpose 

Selects  a  line  of  text  for  editing. 

Syntax 

linenumber 

where: 

linenumber  is  the  number  assigned  by  EDLIN  to  the  text  line  to  be  edited  (1-65534). 

Description 

The  command  to  edit  a  particular  line  of  text  is  simply  the  line’s  number  or  one  of  the  spe¬ 
cial  symbols  or  expressions  that  evaluate  to  a  line  number,  followed  by  the  Enter  key. 
EDLIN  displays  the  current  contents  of  the  specified  line  and  copies  them  to  a  special  edit¬ 
ing  buffer  called  the  template,  then  moves  the  cursor  to  a  new  line  and  displays  a  prompt 
in  the  form  of  the  line  number  followed  by  a  colon  and  an  asterisk.  If  a  line  number  is  not 
specified  (that  is,  if  the  Enter  key  alone  is  pressed  in  response  to  the  EDLIN  prompt), 
EDLIN  displays  the  line  following  the  current  line  and  makes  it  the  current  line. 

The  user  can  change  the  text  of  the  specified  line  by  simply  entering  new  text  followed  by 
a  press  of  the  Enter  key,  leave  the  text  unchanged  by  pressing  Enter  alone,  or  modify  the 
text  by  using  special  editing  keys  to  change  a  portion  of  the  text  that  has  been  placed  in 
the  template.  These  editing  keys  and  their  actions  are 


Key  Action 


FI 

Ylchar 

F3 

Del 

Ylchar 

Esc 

Ins 

F5 

<r- 

Backspace 


Copies  one  character  from  the  template  to  the  new  line. 

Copies  all  characters  up  to  the  specified  character  from  the  template  to  the 
new  line. 

Copies  all  remaining  characters  in  the  template  to  the  new  line. 

Does  not  copy  (skips  over)  one  character. 

Does  not  copy  (skips  over)  all  characters  up  to  the  specified  character. 
Restarts  editing  for  the  current  line,  leaving  the  template  unchanged. 
Enters/exits  character-insert  mode. 

Makes  the  newly  edited  line  the  new  template. 

Copies  one  character  from  the  template  to  the  new  line. 

Deletes  one  character  from  the  new  line. 

Deletes  one  character  from  the  new  line. 


Note:  Computers  that  are  not  IBM-compatible  may  use  a  different  set  of  editing  keys  to 
perform  these  actions. 
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Control  characters  (those  characters  with  ASCII  codes  in  the  range  0-lFH)  cannot  be  in¬ 
serted  into  text  with  the  usual  Control-key  combinations.  Instead,  the  user  must  press  the 
sequence  Ctrl-V,  followed  by  an  uppercase  character  or  symbol.  For  example,  Ctrl-C  (ASCII 
code  03H)  is  entered  into  text  by  pressing  Ctrl-V  followed  by  a  capital  C;  the  Escape  char¬ 
acter  (ASCII  code  IBH)  is  generated  by  pressing  Ctrl-V  followed  by  a  left  square-bracket 
character  ([). 

Examples 

To  edit  line  4,  type 

♦4  <Enter> 

To  edit  the  line  two  lines  ahead  of  the  current  line,  type 

*+2  <Enter> 
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EDLIN:  A  1.0  and  later 

Append  Lines  from  Disk 


Purpose 

Reads  lines  from  the  file  being  edited  into  the  edit  buffer. 

Syntax 

ln]A 

where: 

n  is  the  number  of  lines  to  be  read  from  the  file. 

Description 

If  the  file  being  edited  is  too  large  to  fit  into  the  edit  buffer,  EDLIN  ordinarily  reads  only 
enough  text  to  fill  75  percent  of  the  buffer  when  it  opens  the  file,  reserving  25  percent  of 
the  buffer  for  additions  and  changes  to  the  text.  The  user  must  then  employ  the  Write  Lines 
to  Disk  (W)  and  Append  Lines  from  Disk  (A)  commands  to  write  and  read  successive 
blocks  of  text  until  the  entire  file  has  passed  through  the  edit  buffer. 

The  A  command  alone  has  no  effect  if  the  edit  buffer  is  75  percent  or  more  full.  The  W 
command  must  be  used  to  write  lines  to  the  output  file  and  delete  them  from  the  buffer; 
then  the  A  command  can  read  new  lines  from  the  input  file  and  append  them  to  the  end  of 
the  text  remaining  in  the  buffer. 

The  n  parameter  specifies  the  number  of  lines  to  be  read  from  the  file.  If  n  is  omitted  or 
is  too  large,  EDLIN  reads  only  enough  lines  to  fill  the  editing  buffer  to  75  percent  of  its 
capacity. 

Examples 

To  append  200  lines  from  the  disk  file  to  the  edit  buffer,  type 

*200A  <Enter> 

To  append  as  many  lines  from  the  file  as  possible  (until  the  edit  buffer  is  75  percent  full), 
type 

*A  <Enter> 

Message 

End  of  input  file 

The  last  section  of  the  file  being  edited  has  been  read  into  the  edit  buffer. 
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EDLIN:  C  2.0  and  later 

Copy  Lines 

Purpose 

Copies  one  or  more  lines  from  one  location  in  the  edit  buffer  to  another. 

Syntax 

[first]Xlast],destination[,count]C 

where: 

first 
last 

destination 
count 

Description 

The  Copy  Lines  (C)  command  copies  one  or  more  text  lines,  inserting  the  copied  lines  at 
another  location  in  the  edit  buffer.  The  original  lines  that  were  copied  are  unchanged. 
EDLIN  then  renumbers  the  edit  buffer  and  makes  the  first  copied  line  at  the  destination 
the  new  current  line. 

The  first  2ind  last  line-number  parameters  define  the  block  of  lines  to  be  copied.  (Note 
that  the  first  line  number  must  be  less  than  or  equal  to  the  last  line  number.)  Either  or  both 
of  these  numbers  can  be  omitted  (in  which  case  the  current  line  number  is  used),  but  the 
commas  must  still  be  entered  as  placeholders.  The  destination  parameter  specifies  the 
line  before  which  the  copied  lines  are  to  be  inserted;  it  is  not  optional  and  must  not  fall 
within  the  range  of  line  numbers  specified  by  first  ^nd  last  One  of  the  special  symbols 
.  (current  line)  or  #  (end  of  buffer)  or  an  expression  relative  to  the  current  line  number 
(+«  or  -ri)  can  be  used  instead  of  absolute  line  numbers. 

To  replicate  the  line  or  lines  multiple  times,  the  copy  operation  can  be  repeated  automat¬ 
ically  with  the  optional  parameter  count  The  default  value  for  count  is  one. 

Examples 

If  the  current  line  is  line  10,  to  copy  lines  10  through  15  and  place  the  copied  lines  before 
line  5,  type 

*10,15,5C  <Enter> 

or 

*,15,5C  <Enter> 

or 

*,+5,-5C  <Enter> 


is  the  number  of  the  first  line  to  be  copied, 
is  the  number  of  the  last  line  to  be  copied. 

is  the  number  of  the  line  before  which  the  copied  lines  are  to  appear, 
is  the  number  of  times  to  execute  the  copy  operation. 
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If  the  current  line  is  line  10,  to  place  three  copies  of  lines  10  through  15  before  line  1,  type 

*10,15,1,3C  <Enter> 

or 


*,15,1,3C  <Enter> 


or 


*,+5,1,3C  <Enter> 

Messages 

Entry  error 

The  command  line  contained  an  error  such  as  a  first  line  number  that  was  greater  than  the 
last  line  number  or  a  destination  line  number  that  fell  within  the  range  first, last. 

Insufficient  memory 

The  edit  buffer  does  not  have  sufficient  room  for  EDLIN  to  carry  out  the  specified 
command. 

Must  specify  destination  line  number 

No  destination  line  number  was  specified  in  the  command  line;  therefore,  no  changes 
were  made  to  the  edit  buffer. 
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EDLIN:  D  1.0  and  later 

Delete  Lines 


Puipose 

Deletes  one  or  more  lines  from  the  edit  buffer. 

S^tax 

[first][,last]D 

where: 

first  is  the  number  of  the  first  line  to  delete. 

last  is  the  number  of  the  last  line  to  delete. 

Description 

The  Delete  Lines  (D)  command  removes  one  or  more  text  lines  from  the  edit  buffer.  The 
line  after  the  last  line  deleted  becomes  the  new  current  line. 


The  first  and  last  line-number  parameters  define  the  block  of  lines  to  be  deleted.  (Note 
that  the  first  line  number  must  be  less  than  or  equal  to  the  last  line  number.)  Either  or  both 
of  these  numbers  can  be  omitted  (in  which  case  the  current  line  number  is  used),  but  a 
leading  comma  is  required  as  a  placeholder  if  first  is  omitted  when  last  is  present.  One  of 
the  special  symbols .  (current  line)  or  #  (end  of  buffer)  or  an  expression  relative  to  the  cur¬ 
rent  line  number  (+ w  or  -w)  can  be  used  instead  of  absolute  line  numbers. 

Examples 

If  the  current  line  is  line  10,  to  delete  the  current  line,  type 

*1 OD  <Enter> 


or 


*D  <Enter> 

If  the  current  line  is  line  10,  to  delete  lines  10  through  15,  type 

*1 0, 1 5D  <Enter> 

or 

1 5D  <Enter> 

or 


*, +5D  <Enter> 


Section  III:  User  Commands 


837 


EDLIN:  D 


If  the  current  line  is  line  10,  to  delete  all  lines  from  the  current  line  to  the  end  of  the  buffer, 
type 

*10,#D  <Enter> 

or 

♦ , #D  <Enter> 

Message 

Entry  error 

The  command  line  contained  an  error  such  as  a  first  line  number  that  was  greater  than  the 
last  line  number. 
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EDLIN:  E  1.0  and  later 

End  Editing  Session 


Purpose 

Saves  the  edited  file  to  disk  and  exits  from  EDLIN. 

Syntax 

E 

Description 

The  End  Editing  Session  (E)  command  writes  the  contents  of  the  edit  buffer  to  the  current 
directory  of  the  disk  in  the  current  drive.  If  a  previously  existing  file  was  being  edited  and 
there  is  any  text  remaining  in  the  original  file  that  has  not  yet  passed  through  the  edit 
buffer,  EDLIN  copies  this  text  to  the  output  file.  EDLIN  gives  the  newly  edited  file  the  same 
name  as  the  original  file  and  renames  the  original  (unchanged)  file  with  the  extension 
.BAK.  Any  previous  file  with  the  same  name  and  the  extension  .BAK  is  lost.  EDLIN  then 
returns  to  MS-DOS. 

If  the  disk  does  not  have  enough  space  to  hold  the  edited  file  in  addition  to  the  original 
file,  EDLIN  writes  as  much  of  the  edited  file  as  possible  into  a  file  with  the  extension  .$$$; 
the  remainder  of  the  edited  text  is  lost.  The  name  and  contents  of  the  original  file  are  left 
unchanged. 

Example 

To  end  an  editing  session,  type 

♦E  <Enter> 

Messages 

Disk  fulL  Edits  lost. 

The  disk  does  not  contain  enough  free  space  for  the  edited  file.  A  partial  file  may  have 
been  created  with  the  extension  .$$$. 

File  Creation  Error 

The  .BAK  file  is  marked  read-only,  the  root  directory  is  full  or  cannot  contain  any  more 
files,  or  the  filename  is  the  same  as  a  volume  label  or  directory  name. 

No  room  in  directory  for  file 

The  file  could  not  be  saved  because  its  destination  was  the  root  directory  and  the  root 
directory  is  full. 

Too  many  files  open 

MS-DOS  was  unable  to  open  the  .BAK  file  due  to  a  lack  of  available  system  file  handles. 
Increase  the  value  of  the  FILES  command  in  the  CONFIG.SYS  file. 
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EDLIN:  I  1.0  and  later 

Insert  Lines 


Purpose 

Inserts  new  lines  into  the  edit  buffer. 

Syntax 

[destinationM 

where: 

destination  is  the  number  of  the  line  before  which  text  is  to  be  inserted. 

Description 

The  Insert  Lines  (I)  command  enables  insert  mode  and  allows  new  text  to  be  placed  be¬ 
tween  previously  existing  lines  of  text.  When  insert  mode  is  terminated,  the  first  line  fol¬ 
lowing  the  inserted  lines  becomes  the  new  current  line. 

EDLIN  places  the  new  text  before  the  line  specified  by  the  destination  parameter.  If 
destination  is  omitted,  EDLIN  assumes  the  current  line;  if  destination  is  larger  than  the 
number  of  lines  in  the  edit  buffer,  EDLIN  simply  appends  the  new  text  after  the  actual  last 
line.  One  of  the  special  symbols .  (current  line)  or  #  (end  of  buffer)  or  an  expression  rela¬ 
tive  to  the  current  line  number  (+ w  or  -n)  can  be  used  instead  of  an  absolute  line  number. 

After  an  I  command,  EDLIN  issues  a  prompt  consisting  of  the  line  number  for  the  inserted 
text  followed  by  a  colon  and  an  asterisk  and  continues  to  issue  such  prompts  each  time  the 
Enter  key  is  pressed  until  the  user  terminates  insert  mode  by  pressing  Ctrl-C  or  Ctrl-Break. 

Examples 

If  the  current  line  is  line  10,  to  insert  text  before  line  7,  type 

*71  <Enter> 

or 

♦-3I  <Enter> 

To  insert  lines  at  the  beginning  of  the  buffer,  type 

*1 1  <Enter> 

To  insert  lines  at  the  end  of  the  buffer,  type 

*#I  <Enter> 

Message 

Insufficient  memory 

The  edit  buffer  does  not  have  sufficient  room  for  EDLIN  to  complete  the  specified 
command. 


840  The  MS-DOS  Encyclopedia 


EDLIN:  L 


EDLIN:  L  1.0  and  later 

List  Lines 


Purpose 

Displays  one  or  more  lines  from  the  edit  buffer. 

Syntax 

[first\[,last]L 

where: 

first  is  the  number  of  the  first  line  to  be  displayed. 

last  is  the  number  of  the  last  line  to  be  displayed. 

Description 

The  List  Lines  (L)  command  displays  text  lines  on  standard  output.  If  the  current  line  lies 
within  the  range  of  lines  listed,  EDLIN  displays  an  asterisk  next  to  its  number.  The  current 
line  is  not  changed. 

The  first  3.nd  last  line-number  parameters  define  the  block  of  lines  to  be  listed.  (Note  that 
the  first  line  number  must  be  less  than  or  equal  to  the  last  line  number.)  Either  or  both  of 
these  numbers  can  be  omitted,  but  a  leading  comma  is  required  as  a  placeholder  if first  is 
omitted  when  last  is  present.  One  of  the  special  symbols .  (current  line)  and  #  (end  of 
buffer)  or  an  expression  relative  to  the  current  line  number  (+n  or  -n)  can  be  used  instead 
of  absolute  line  numbers. 

If  only  the  first  line  number  is  specified,  EDLIN  displays  text  in  23dine  increments  starting 
with  that  number.  If  only  the  last  line  number  is  specified,  EDLIN  displays  text  beginning 
11  lines  before  the  current  line  and  continuing  to  the  specified  last  line.  If  no  line  numbers 
are  specified  in  the  command,  EDLIN  lists  the  23  lines  centered  around  the  current  line;  if 
the  current  line  number  is  less  than  13,  EDLIN  lists  the  first  23  lines  in  the  buffer. 

Examples 

To  display  lines  20  through  30,  type 

*20,30L  <Enter> 

If  the  current  line  is  20,  to  display  the  23  lines  centered  around  the  current  line,  type 

*L  <Enter> 

EDLIN  displays  lines  9  through  31. 

Message 

Entry  error 

The  command  line  contained  an  error  such  as  a  first  line  number  that  was  greater  than  the 
last  line  number. 
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EDLIN:  M  2.0  and  later 

Move  Lines 


Purpose 

Moves  lines  from  one  place  in  the  edit  buffer  to  another. 

Syntax 

[first], [last\destinationyi 
where: 

first  is  the  number  of  the  first  line  to  be  moved. 

last  is  the  number  of  the  last  line  to  be  moved. 

destination  is  the  number  of  the  line  before  which  the  moved  lines  are  to  be  inserted. 

Description 

The  Move  Lines  (M)  command  transfers  one  or  more  text  lines  from  one  location  in  the 
edit  buffer  to  another.  EDLIN  then  deletes  the  original  lines  and  renumbers  the  edit  buffer. 
The  first  moved  line  becomes  the  new  current  line. 

The  first  and  last  line-number  parameters  define  the  block  of  lines  to  be  moved.  (Note 
that  the  first  line  number  must  be  less  than  or  equal  to  the  last  line  number.)  Either  or  both 
of  these  numbers  can  be  omitted  (in  which  case  the  current  line  number  is  used),  but  the 
commas  must  still  be  entered  as  placeholders.  The  destination  parameter  specifies  the 
line  before  which  the  moved  lines  are  to  be  inserted;  it  is  not  optional  and  must  not  fall 
within  the  range  of  line  numbers  specified  by  first  2ind  last.  One  of  the  special  symbols 
.  (current  line)  or  #  (end  of  buffer)  or  an  expression  relative  to  the  current  line  number 
(+n  or  -«)  can  be  used  instead  of  absolute  line  numbers. 

Example 

If  the  current  line  is  line  10,  to  move  lines  10  through  15  and  place  them  before  line  5,  type 

*10,15,5M  <Enter> 

or 

*,15,5M  <Enter> 

or 


♦,+5,-5M  <Enter> 
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Messages 

Entry  error 

The  command  line  contained  an  error  such  as  a  first  line  number  that  was  greater  than  the 
last  line  number  or  a  destination  line  number  that  fell  within  the  range  first, last. 

Must  specify  destination  line  number 

No  destination  line  number  was  specified  in  the  command  line;  therefore,  no  changes 
were  made  to  the  edit  buffer. 
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EDLIN:  P  2.0  and  later 

Display  in  Pages 


Purpose 

Displays  lines  for  viewing  in  successive  screenfuls  (pages). 

Syntax 

[first][,last]? 

where: 

first  is  the  number  of  the  first  line  to  be  displayed. 

last  is  the  number  of  the  last  line  to  be  displayed. 

Description 

The  Display  in  Pages  (P)  command  displays  text  lines  on  standard  output  one  screenful 
at  a  time.  Unlike  the  List  Lines  (L)  command,  which  has  no  effect  on  the  current  line,  P 
causes  the  last  line  displayed  to  become  the  new  current  line.  Thus,  although  the  edit 
buffer  is  not  actually  organized  into  pages,  the  user  can  employ  repeated  P  commands  to 
sequentially  view  successive  groups  of  lines. 

The  first  and  last  line-number  parameters  define  the  block  of  lines  to  be  listed;  the  dis¬ 
play  starts  with  the  line  specified  by  first  (Note  that  the  first  line  number  must  be  less 
than  or  equal  to  the  last  line  number.)  Either  or  both  of  these  numbers  can  be  omitted,  but 
a  leading  comma  is  required  as  a  placeholder  if  first  is  omitted  when  last  is  present.  If 
omitted,  first  defaults  to  the  line  after  the  current  line  and  last  defaults  to  the  line  23  lines 
after  the  current  line.  One  of  the  special  symbols .  (current  line)  or  #  (end  of  buffer)  or  an 
expression  relative  to  the  current  line  number  (+ w  or  -w)  can  be  used  instead  of  absolute 
line  numbers. 

Examples 

If  the  current  line  is  20,  to  view  the  next  page  of  lines  in  the  edit  buffer,  type 

*P  <Enter> 

EDLIN  displays  23  lines,  beginning  with  line  21,  and  changes  the  current  line  to  line  43. 

To  view  successive  pages  of  23  lines,  repeatedly  type 

*P  <Enter> 

Message 

Entry  error 

The  command  line  contained  an  error  such  as  a  first  line  number  that  was  greater  than  the 
last  line  number. 
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EDLIN:  Q  1.0  and  later 

Quit 


Purpose 

Terminates  the  editing  session  without  saving  the  revised  file. 

Syntax 

Q 

Description 

The  Quit  (Q)  command  causes  EDLIN  to  exit  without  saving  any  of  the  changes  made  to 
the  edited  file  during  the  session.  The  original  file's  name  and  contents  are  left  unchanged 
and  no  new  file  is  created. 

To  reduce  the  danger  of  accidentally  losing  the  contents  of  the  edit  buffer,  EDLIN  prompts 
the  user  for  confirmation  before  carrying  out  the  Q  command. 

Example 

To  quit  an  editing  session,  type 

*Q  <Enter> 

EDLIN  issues  a  prompt  for  confirmation  and,  if  the  response  from  the  user  is  Y,  exits  to 
MS-DOS  without  saving  any  changes  made  to  the  file  during  the  session. 

Message 

Abort  edit  (Y/N)? 

This  prompt  is  displayed  in  response  to  the  Q  command.  Respond  with  Y  to  exit  to 
MS-DOS  without  saving  changes  made  to  the  file;  respond  with  N  to  continue  the  editing 
session. 
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EDLIN:  R  1.0  and  later 

Replace  Text 

Puipose 

Replaces  one  string  in  the  edit  buffer  with  another. 

Syntax 

[first]  [,last]  \3!\R[stringl  ]  [^Zstring2] 
where: 

first  is  the  number  of  the  first  line  to  be  searched. 

last  is  the  number  of  the  last  line  to  be  searched. 

?  causes  the  user  to  be  prompted  for  confirmation  before  each  replacement  is 

made. 

stringl  is  the  sequence  of  characters  to  be  searched  for. 

^2  is  a  Control-Z  character. 

string2  is  the  sequence  of  characters  to  be  substituted  for  stringl. 

Note:  The  character  limit  for  the  Replace  Text  command  is  127  characters,  including  both 
strings  and  all  other  parameters. 

Description 

The  Replace  Text  (R)  command  substitutes  one  character  string  for  another  within  a  speci¬ 
fied  range  of  lines.  The  last  line  in  which  a  replacement  occurs  becomes  the  new  current 
line. 

The  first  and  last  line-number  parameters  define  the  range  of  lines  to  be  searched  for 
strings  to  replace.  (Note  that  the  first  line  number  must  be  less  than  or  equal  to  the  last  line 
number.)  Either  or  both  of  these  numbers  can  be  omitted,  but  a  leading  comma  is  required 
as  a  placeholder  if  first  is  omitted  when  last  is  present.  If  omitted,  first  defaults  to  the 
line  after  the  current  line  and  last  defaults  to  the  last  line  in  the  buffer.  One  of  the  special 
symbols .  (current  line)  or  #  (end  of  buffer)  or  an  expression  relative  to  the  current  line 
number  (+n  or  -n)  can  be  used  instead  of  absolute  line  numbers. 

If  stringl  is  omitted,  EDLIN  uses  the  stringl  from  the  preceding  R  command;  if  there  was 
no  preceding  R  command,  EDLIN  displays  an  error  message.  If  string2  is  omitted,  EDLIN 
deletes  all  occurrences  of  stringl.  stringl  must  be  separated  from  string2  by  a  Control-Z 
(^2)  character.  If  stringl  is  omitted,  a  Control-Z  character  must  still  be  included  to  mark 
the  beginning  of  string2,  but  if  string2  is  omitted  when  stringl  is  present,  the  Control-Z 
character  has  no  effect  and  is  therefore  optional.  (The  Control-Z  character  is  entered  by 
pressing  Ctrl-Z  or  the  F6  key.) 
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If  the  ?  option  is  not  included  in  the  command  line,  EDLIN  displays  each  line  that  contains 
a  match  after  the  replacement  is  carried  out.  If  the  ?  option  is  used,  EDLIN  displays  each 
line  containing  a  match  as  it  is  found  and  prompts  the  user  for  confirmation  before  the 
string  is  replaced. 

The  matching  operation  is  case  sensitive;  EDLIN  carries  out  the  substitution  only  on 
sequences  of  characters  that  match  string!  exactly.  Wildcards  are  not  permitted. 

Examples 

If  the  current  line  is  line  10,  to  replace  all  occurrences  of  the  string  logical  with  the  string 
bitwise  in  lines  11  through  20,  type 

*1 1 , 20Rlogical^Zbitwise  <Enter> 

or 

*,  20Rlogical''Zbitwise  <Enter> 

To  cause  EDLIN  to  prompt  for  confirmation  before  replacing  each  string,  type 

*1 1 , 20?Rlogical''Zbitwise  <Enter> 

or 

*,  20?Rlogical''Zbitwise  <Enter> 

To  delete  all  occurrences  of  the  string  OOH  in  line  20,  type 

*20,20R00H''Z  <Enter> 

Messages 

Entry  error 

The  command  line  contained  an  error  such  as  a  first  line  number  that  was  greater  than  the 
last  line  number. 

Insufficient  memory 

The  edit  buffer  has  insufficient  room  for  EDLIN  to  carry  out  the  specified  Replace  Text 
command. 

Line  too  long 

The  replacement  would  cause  the  line  being  edited  to  expand  beyond  253  characters. 

Not  found 

No  occurrence  or  further  occurrences  of  the  string  to  be  replaced  were  found  in  the  speci¬ 
fied  range  of  lines. 

O.K.? 

If  the  ?  option  is  used  in  the  command  line,  this  prompt  is  displayed  each  time  a  matching 
string  is  found.  Respond  with  Y  or  press  the  Enter  key  to  replace  the  string  and  continue 
searching;  press  any  other  key  to  leave  the  string  unchanged  and  continue  searching. 
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EDLIN:  S  1.0  and  later 

Search  for  Text 


Purpose 

Searches  the  edit  buffer  for  a  character  string. 

Syntax 

[ first]  [.last]  U]S{string] 
where: 

first  is  the  number  of  the  first  line  to  be  searched. 

last  is  the  number  of  the  last  line  to  be  searched. 

?  causes  the  user  to  be  prompted  for  confirmation  before  the  search  is 

terminated. 

string  is  the  sequence  of  characters  to  be  searched  for  (maximum  126  characters). 

Description 

The  Search  for  Text  (S)  command  searches  for  a  character  string  within  a  specified  range 
of  lines.  When  a  match  is  found,  EDLIN  displays  the  line  containing  the  match  and  that 
line  becomes  the  new  current  line.  If  no  lines  containing  the  specified  string  are  found, 
EDLIN  displays  the  message  Not found  and  the  current  line  number  remains  unchanged. 

The  first  and  last  line-number  parameters  define  the  block  of  lines  to  be  searched  for 
strings.  (Note  that  the  first  line  number  must  be  less  than  or  equal  to  the  last  line  number.) 
Either  or  both  of  these  numbers  can  be  omitted,  but  a  leading  comma  is  required  as  a 
placeholder  if  first  is  omitted  when  last  is  present.  If  omitted,  first  defaults  to  the  line 
after  the  current  line  and  last  defaults  to  the  last  line  in  the  buffer.  One  of  the  special 
symbols .  (current  line)  or  #  (end  of  buffer)  or  an  expression  relative  to  the  current  line 
number  (+n  or  -n)  can  be  used  instead  of  absolute  line  numbers. 

If  string  is  omitted,  EDLIN  uses  the  string  from  the  last  S  command  or  stringl  from  the 
last  Replace  Text  (R)  command  instead. 

If  the  ?  option  is  not  included  in  the  command  line,  EDLIN  displays  the  first  line  that  con¬ 
tains  a  match  for  string,  makes  this  the  new  current  line,  and  terminates  the  search.  If  the 
?  option  is  used,  EDLIN  displays  each  line  containing  a  match  for  string  as  it  is  found,  fol¬ 
lowed  by  an  O.K.?  prompt.  If  the  user  responds  with  Y  or  presses  the  Enter  key,  EDLIN  ter¬ 
minates  the  search;  if  the  user  presses  any  other  key,  the  search  continues. 

The  matching  operation  is  case  sensitive;  EDLIN  reports  only  sequences  of  characters  that 
match  string  exactly.  Wildcards  are  not  permitted. 
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Examples 

If  the  current  line  is  line  10,  to  find  the  first  occurrence  of  the  string  xyz  in  lines  11  through 
20,  type 

*11,20Sxyz  <Enter> 

or 

*,20Sxyz  <Enter> 

To  find  a  particular  occurrence  of  proc  in  the  edit  buffer,  type 

*1,#?Sproc  <Enter> 

EDLIN  displays  the  first  line  containing  proc  and  prompts  with 

O.K.? 

Type  Y  or  press  Enter  to  stop  the  search;  press  any  other  key  to  continue  the  search. 

Messages 

Entry  error 

The  command  line  contained  an  error  such  as  a  first  line  number  that  was  greater  than  the 
last  line  number. 

Not  found 

No  match  or  no  further  matches  for  string  were  found  in  the  specified  range  of  lines. 

O.IL? 

If  the  ?  option  is  used  in  the  command  line,  this  prompt  is  displayed  each  time  a  matching 
string  is  found.  Respond  with  Y or  press  the  Enter  key  to  stop  searching;  press  any  other 
key  to  continue  searching. 
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EDLIN:  T  2.0  and  later 

Transfer  Another  File 


Purpose 

Merges  the  contents  of  another  file  with  the  file  in  the  edit  buffer. 

Syntax 

[destination\T[driw][patli\filename 
where: 
destination 

path 
filename 

Description 

The  Transfer  Another  File  (T)  command  merges  the  contents  of  a  text  file  with  the  current 
contents  of  the  edit  buffer  and  then  renumbers  the  contents  of  the  edit  buffer.  The  first  line 
of  the  merged  text  becomes  the  current  line. 

The  destination  parameter  specifies  the  line  before  which  the  transferred  lines  are  to  be 
inserted.  If  omitted,  destination  defaults  to  the  current  line.  One  of  the  special  symbols 
.  (current  line)  or  #  (end  of  buffer)  or  an  expression  relative  to  the  current  line  number 
(+ w  or  -n)  can  be  used  instead  of  an  absolute  line  number. 

The  filename  parameter  specifies  the  file  from  which  text  is  to  be  merged  and  can  include 
a  drive  and,  in  versions  3.0  and  later,  a  path.  If  a  drive  or  path  is  not  specified,  the  file  to 
be  merged  into  the  edit  buffer  with  the  T  command  must  be  in  the  current  directory  of  the 
current  drive. 

Example 

If  the  current  line  is  line  10,  to  merge  the  contents  of  the  file  named  KEYDEFS.C  before 
line  10  of  the  edit  buffer,  type 

*1 OTkeydefs.c  <Enter> 

or 

♦Tkeydefs.c  <Enter> 


is  the  number  of  the  line  before  which  the  text  from  filename  is  to  be 
inserted. 

is  the  location  of  the  file  to  be  merged  (versions  3.0  and  later), 
is  the  name  of  the  disk  file  from  which  text  is  to  be  merged. 


850  The  MS-DOS  Encyclopedia 


EDLIN:  T 


Messages 

File  not  found 

The  specified  filename  does  not  exist  in  the  current  or  specified  location. 

Not  enough  room  to  merge  the  entire  file 

The  space  available  in  the  edit  buffer  is  not  sufficient  to  hold  the  entire  file  named  in  the  T 
command.  Use  the  Write  Lines  to  Disk  (W)  command  to  partially  empty  the  edit  buffer. 
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EDLIN:  W  1.0  and  later 

Write  Lines  to  Disk 


Purpose 

Writes  lines  from  the  edit  buffer  to  the  disk. 

Syntax 

[w]W 

where: 

n  is  the  number  of  lines  to  be  written  to  the  file. 

Description 

If  the  file  being  edited  is  too  large  to  fit  into  the  edit  buffer,  EDLIN  ordinarily  reads  only 
enough  text  to  fill  75  percent  of  the  buffer  when  it  opens  the  file,  reserving  25  percent  of 
the  buffer  for  changes  and  additions  to  the  text.  The  user  must  then  employ  the  Write  Lines 
to  Disk  (W)  command  and  the  Append  Lines  from  Disk  (A)  command  to  transfer  succes¬ 
sive  blocks  of  text  from  the  disk  until  the  entire  file  has  passed  through  the  edit  buffer.  The 
W  command  causes  EDLIN  to  write  lines  to  the  disk  file  and  delete  them  from  the  buffer; 
then  the  A  command  can  read  new  lines  from  the  input  file,  placing  them  after  the  end  of 
the  text  remaining  in  the  buffer. 

The  n  parameter  specifies  the  number  of  lines  to  be  written  to  the  output  file;  if  n  is  omit¬ 
ted  or  is  larger  than  the  number  of  lines  in  the  edit  buffer,  EDLIN  writes  only  enough  lines 
to  leave  the  edit  buffer  about  25  percent  full.  EDLIN  then  renumbers  the  lines  remaining  in 
the  edit  buffer  so  that  the  first  remaining  line  becomes  line  number  one. 

Examples 

To  write  200  lines  from  the  edit  buffer  to  disk  (effectively  deleting  those  lines  from  the 
buffer),  type 

*200W  <Enter> 

To  write  lines  from  the  edit  buffer  to  the  disk  until  the  edit  buffer  is  only  25  percent  full, 
type 

*W  <Enter> 
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EXIT  2.0  and  later 

Terminate  Command  Processor  internal 


Purpose 

Terminates  a  secondary  copy  of  the  command  processor. 

Syntax 

EXIT 

Description 

Many  communications  programs,  word  processors,  database  managers,  and  other  applica¬ 
tion  programs  load  and  execute  a  secondary  copy  of  the  system’s  command  processor 
(COMMAND.COM)  to  let  the  user  carry  out  MS-DOS  commands  without  losing  the  context 
of  the  work  in  progress.  Secondary  copies  of  the  command  processor  are  also  commonly 
used  to  execute  one  batch  file  under  the  control  of  another.  (For  more  information  about 
secondary  copies  of  the  command  processor,  see  USER  COMMANDS:  command.) 

The  EXIT  command  cancels  a  secondary  command  processor.  The  terminating  processor 
displays  no  message  and  control  returns  directly  to  the  parent  program  or  command 
processor. 

EXIT  has  no  effect  on  the  currently  executing  command  processor  if  it  was  loaded  with 
the  /P  (permanent)  switch  or  if  it  is  the  original  command  processor  (the  one  loaded  dur¬ 
ing  system  initialization,  when  the  computer  was  turned  on  or  restarted). 

The  EXIT  command  also  allows  the  user  to  choose  Close  from  the  system  menu  if  a 
COMMAND  window  is  open  under  Microsoft  Windows. 

Example 

To  terminate  the  currently  executing  command  processor,  type 

OEXIT  <Enter> 

Message 

Bad  command  or  filename 

The  EXIT  command  did  not  exist  in  versions  earlier  than  2.0,  so  MS-DOS  attempted  to 
execute  a  nonexistent  program  named  EXIT  instead. 
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FC 

Compare  Files 


2.0  and  later 
External 


Purpose 

Compares  two  files  and  lists  the  differences  on  standard  output. 

Syntax 

FC  [/A]  [/C]  l/L]  [/LBw]  [/N]  l/nnnn]  l/T]  [/W]  [drive\\pathnamel  [drive\\pathname2 


or 


FC  [/B]  [drive']pathnamel  [drive{\pathname2 
where: 


pathnamel 

pathnaYne2 

/A 

/B 

/C 

/L 

/LBw 

/N 

Innnn 


n 

/w 

Description 


is  the  name  and  location  of  the  first  file  to  be  compared,  optionally  pre¬ 
ceded  by  a  drive;  wildcard  characters  are  not  permitted, 
is  the  name  and  location  of  the  second  file  to  be  compared,  optionally  pre¬ 
ceded  by  a  drive;  wildcard  characters  are  not  permitted, 
causes  FC  to  abbreviate  the  output  when  comparing  ASCII  text  files 
(version  3.2). 

causes  a  byte-by-byte  (binary)  comparison;  may  not  be  used  with  any 
other  switch  (default  when  file  extension  is  .EXE,  .COM,  .SYS,  .OBJ,  .LIB, 
or  .BIN). 

causes  FC  to  ignore  case  when  comparing  alphabetic  characters, 
causes  a  line-by-line  comparison  of  two  ASCII  text  files  (default  when  file 
extension  is  not  .EXE,  .COM,  .SYS,  .OBJ,  .LIB,  or  .BIN)  (version  3.2). 
sets  the  size  of  the  internal  line  buffer  to  n  lines  (default  =  100) 

(version  3-2). 

includes  line  numbers  on  the  output  of  an  ASCII  file  comparison 
(version  3.2). 

is  the  number  of  lines  that  must  match  to  resynchronize  during  an  ASCII 
file  comparison  (default  =  2;  in  versions  2.0  through  3.1,  range  =  1-9, 
default  =  3). 

causes  FC  to  compare  tabs  in  text  files  literally  (default  =  tabs  expanded  to 
spaces,  with  stops  at  each  eighth  character  position)  (version  3.2). 
causes  FC  to  ignore  spaces,  tabs,  and  blank  lines  in  text  files. 


The  FC  utility  compares  two  text  files  containing  lines  of  ASCII  text  delimited  by  new-line 
characters  or  two  binary  files  containing  data  of  any  type  (such  as  executable  programs). 
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The  differences  between  the  two  files  are  listed  on  standard  output,  which  defaults  to  the 
video  display  but  can  be  redirected  to  another  character  device  or  a  file  or  can  be  piped  to 
another  program. 

The  FC  program  first  examines  the  extensions  of  the  two  files  being  compared  and,  in 
most  cases,  selects  the  appropriate  type  of  comparison  automatically.  However,  the  /B 
switch  can  be  used  to  force  a  binary,  or  byte-by-byte,  comparison  of  the  two  files  named; 
the  /L  switch  can  be  used  to  force  a  line-by-line  comparison.  When  the  /B  switch  is 
present,  use  of  the  /L,  /N,  and  /nnnn  switches  causes  an  error  message  to  be  displayed; 
any  other  switches  in  the  command  line  are  ignored. 

When  comparing  ASCII  text  files,  FC  loads  a  buffer  with  sequential  sets  of  lines  from  each 
file  and  compares  the  two  sets.  The  size  of  this  buffer  defaults  to  100  lines  but  can  be  modi¬ 
fied  by  including  the  /LBw  switch  in  the  command  line.  If  differences  are  found,  the  name 
of  the  first  file,  the  last  matched  line,  and  any  mismatched  lines  from  that  file  are  dis¬ 
played,  followed  by  the  first  rematched  line;  then  the  name  of  the  second  file,  the  last 
matched  line,  and  any  mismatched  lines  are  displayed,  followed  by  the  first  rematched 
line  from  that  file.  The  number  of  consecutive  matching  lines  that  must  be  detected  in 
order  for  FC  to  consider  the  files  resynchronized  is  controlled  with  the  /nnnn  switch;  the 
default  is  2. 

If  no  lines  match,  if  no  lines  match  after  the  first  mismatch,  or  if  the  number  of  mis¬ 
matched  lines  exceeds  the  size  of  the  line  buffer,  FC  displays  the  message  Resynch  failed. 
Files  are  too  different  (or  ***Files  are  different***  in  versions  2.x  and  3.0)  and  terminates. 

The  /C,  /T,  and  /  W  switches  modify  the  way  in  which  two  text  files  are  compared.  The 
/C  switch  causes  FC  to  ignore  case  when  comparing  alphabetic  characters.  The  /T  switch 
causes  FC  to  compare  tab  characters  (ASCII  code  09H)  literally,  rather  than  expand  them 
to  spaces  before  comparing  corresponding  lines.  Finally,  the  /W,  or  whitespace,  switch 
causes  FC  to  ignore  spaces,  tabs,  and  blank  lines  during  the  comparison. 

The  /A  and  /N  switches  control  the  format  of  the  listing  of  differences  between  the  two 
text  files.  The  /A  switch  causes  FC  to  compress  the  listing  of  each  mismatched  set  of  lines 
to  the  first  and  last  lines  of  each  set,  separated  by  ellipsis  points.  The  /N  switch  causes  FC 
to  include  the  line  numbers  of  the  mismatched  lines  in  the  display. 

During  a  binary  comparison  of  two  files,  FC’s  buffer  is  reloaded  as  many  times  as  is  neces¬ 
sary  to  compare  the  complete  files.  Unlike  the  procedure  with  text-file  comparisons,  no  at¬ 
tempt  is  made  to  resynchronize  the  data  if  a  mismatch  is  detected  and,  regardless  of  the 
number  of  mismatches,  the  comparison  process  is  not  terminated.  Any  differences  are  dis¬ 
played  with  the  offset  from  the  start  of  the  file  and  the  actual  data  from  each  file.  If  one  file 
is  shorter  than  the  other,  FC  also  displays  a  warning  message  at  the  end  of  the  comparison. 

The  FC  command  is  present  only  in  MS-DOS.  PC-DOS  versions  1.0  and  later  provide  a 
similar  function  in  the  COMP  command. 
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FC 


Examples 

Assume  that  FILE1.TXT  and  FILE2.TXT  are  in  the  current  directory  on  the  disk  in  the  cur¬ 
rent  drive  and  that  they  contain  the  following  lines: 

FILE1.TXT  FILE2.TXT 


First  line. 
Second  line. 
Third  line. 
Fourth  line. 
Fifth  line. 
Sixth  line. 
Seventh  line 
Eighth  line. 
Ninth  line. 
Tenth  line. 


First  line. 
Second  line. 
Third  line. 
Fourth  line. 
Sixth  line. 
Fifth  line. 
Seventh  line 
Eighth  line. 
Ninth  line. 
Tenth  line. 


To  compare  these  files  line  by  line,  type 


OFC  FILE1.TXT  FILE2.TXT  <Enter> 

This  will  result  in  the  following  display: 


file1.txt 
Fourth  line. 
Fifth  line. 
Sixth  line. 
Seventh  line. 
*****  file2.txt 
Fourth  line. 
Sixth  line. 
Fifth  line. 
Seventh  line. 


To  compare  the  same  two  files  and  produce  an  abbreviated  listing  of  differences  that  in¬ 
cludes  line  numbers,  type 

OFC  /A  /N  FILE1.TXT  FILE2.TXT  <Enter> 

This  will  result  in  the  following  display: 

♦***♦  file1.txt 

4:  Fourth  line. 


7:  Seventh  line. 

*****  file2.txt 

4:  Fourth  line. 

7:  Seventh  line. 
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Assume  that  two  binary  files,  FILE1.BIN  and  FILE2.BIN,  are  the  same  length  and  contain 
only  the  following  three  differences: 


offset 

FILE1.BIN 

FILE2.BIN 

1  9H 

04H 

03H 

33H 

4AH 

4BH 

42H 

52H 

51H 

To  compare  these  two  binary  files,  type 

OFC  /B  FILE1.BIN  FILE2.BIN  <Enter> 

This  will  result  in  the  following  display: 

00000019:  04  03 
00000033:  4A  4B 
00000042:  52  51 

Note:  The  use  of  the  /B  switch  in  this  example  is  optional;  binary  comparison  is  the 
default  when  .BIN  files  are  compared. 

Messages 

y^leifaiff^longerthan  filename 

After  all  the  corresponding  data  in  the  two  files  was  compared,  data  remained  in  one  of 
the  files. 

cannot  open  filename  -  No  such  file  or  directory 

The  specified  file  cannot  be  found  or  does  not  exist. 

DOS  2.0  or  later  required 

FC  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Incompatible  switches 

The  /B  switch  was  used  in  combination  with  one  or  more  of  the  other  switches. 

Incorrect  DOS  version 

The  version  of  FC  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

no  differences  encountered 

The  two  files  being  compared  are  identical. 

out  of  memory 

The  available  memory  in  the  transient  program  area  is  insufficient  to  compare  the  two 
files. 

Resynch  failed.  Files  are  too  different 

The  number  of  mismatched  lines  in  an  ASCII  file  comparison  exceeded  the  number  of 
lines  that  can  be  loaded  into  FC’s  comparison  buffer  (which  by  default  is  100  lines).  Rerun 
the  comparison  using  the  /LBw  switch  to  allocate  a  larger  buffer. 

usage:  fc  [/a]  [/b]  [/c]  [/I]  [/IbNN]  [/w]  [/t]  [/n]  [/NNNN]  fUel  me2 

The  command  line  included  an  invalid  switch  or  FC  was  entered  without  any  switches  or 
other  parameters. 
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FDISK 


FDISK  32 

Configure  Fixed  Disk  External  No  Net 


Purpose 

Configures  an  MS-DOS  partition  on  a  fixed  disk.  This  command  is  included  with  PC-DOS 
beginning  with  version  2.0. 

Syntax 

FDISK 

Description 

A  fixed  disk  can  be  divided  into  areas  of  contiguous  tracks,  or  partitions,  that  are  used  by 
different  operating  systems.  A  master  control  record  (partition  table)  on  the  disk  specifies 
the  ID  number  and  the  starting  and  ending  disk  tracks  for  each  partition.  Each  fixed  disk 
can  have  as  many  as  four  partitions,  but  only  one  partition  can  be  active  (bootable)  at  any 
given  time. 

The  FDISK  utility  is  a  menu-driven  program  that  adds  or  deletes  an  MS-DOS  partition  on  a 
fixed  disk,  selects  one  partition  as  active,  and  displays  the  size  and  status  of  all  partitions. 
With  most  implementations  of  MS-DOS,  each  fixed  disk  can  contain  only  one  MS-DOS 
partition. 

After  an  MS-DOS  partition  is  created,  the  FORMAT  command  must  be  used  to  initialize  the 
partition’s  directory  structure.  To  make  it  possible  to  start  the  computer  from  the  MS-DOS 
partition  on  the  fixed-disk  drive,  the  /S  switch  must  be  used  with  FORMAT  to  transfer  the 
operating-system  files  and  the  MS-DOS  partition  must  be  the  active  partition. 

Warning:  If  the  MS-DOS  partition  is  deleted,  any  files  stored  in  the  partition  are  irretriev¬ 
ably  lost. 

Examples 

To  display  the  current  partitioning  of  the  fixed  disk,  type 

OFDISK  <Enter> 
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The  FDISK  utility  then  displays  the  following  menu: 

Fixed  Disk  Setup  Program  Version  0.02 
(C)  Copyright  Microsoft,  1985. 

FDISK  Options 

Choose  one  of  the  following: 

1 .  Create  DOS  Partition 

2.  Change  Active  Partition 

3.  Delete  DOS  Partition 

4.  Display  Partition  Data 

Enter  choice: [1] 

Press  ESC  to  return  to  DOS 

Note:  A  fifth  option,  Select  Next  Fixed  Drive,  will  appear  if  more  than  one  fixed  disk  is  in¬ 
stalled  in  the  system. 

Choose  option  4  Wisplay  Partition  DaUd.  FDISK  then  displays  the  partition  data  for  the 
disk  in  the  following  form: 

Display  Partition  Information 

Partition  Status  Type  Start  End  Size 

1  A  DOS  0  613  614 

Total  disk  space  is  614  cylinders. 

Press  ESC  to  return  to  FDISK  Options 

Assume  that  the  low-level  (hardware)  formatting  for  fixed-disk  drive  C  has  just  been  com¬ 
pleted  by  using  the  drive  manufacturer’s  setup  utility.  To  establish  a  bootable  MS-DOS  par¬ 
tition  on  the  disk,  type 

A>FDISK  <Enter> 

When  the  menu  is  displayed,  press  Enter  to  choose  option  1  (^Create  DOS  Partition).  FDISK 
responds  with  the  following  message: 

Create  DOS  Partition 

Do  you  wish  to  use  the  entire  fixed 

disk  for  DOS  (Y/N) . ?[Y] 

Press  ESC  to  return  to  FDISK  Options 

To  partition  the  entire  fixed  disk  for  MS-DOS,  press  Enter  to  select  Y  (the  default).  When 
the  FDISK  main  menu  is  again  displayed,  choose  option  4  (.Display  Partition  Data)  to 
verify  that  the  MS-DOS  partition  has  in  fact  been  established  on  the  fixed  disk. 
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Messages 

«  is  not  a  choice.  Please  enter  Y  or  N. 

The  response  to  an  FDISK  prompt  requiring  a  yes  or  no  answer  was  not  T  or 

If  is  not  a  choice.  Please  enter  a  choice 

The  response  to  an  FDISK  prompt  requiring  a  number  was  not  in  the  proper  range  or  was 
not  a  number. 

DOS  partition  created 

A  new  MS-DOS  partition  has  been  established  on  the  fixed  disk.  Use  the  FORMAT  utility 
to  create  a  directory  structure  in  that  partition. 

DOS  partition  deleted 

The  previously  existing  MS-DOS  partition  on  the  fixed  disk  has  been  deleted.  Any  files 
contained  in  the  partition  are  irretrievably  lost 

DOS  2.0  or  later  required 

FDISK  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Do  you  wish  to  use  the  entire  fixed 
disk  for  DOS  (Y/N) . ?[Y] 

Option  1,  Create  DOS  Partition,  has  been  chosen  from  the  main  menu.  Respond  with  Y  or 
press  Enter  to  use  all  available  cylinders  for  a  single  DOS  partition;  respond  with  N  to 
specify  that  only  part  of  the  fixed  disk  should  be  used. 

Enter  starting  cylinder  number. . :[»] 

Option  1,  Create  DOS  Partition,  has  been  chosen  from  the  main  menu  and  the  user  has  re¬ 
sponded  N  to  the  Do  you  wish  to  use  the  entire fixed  disk for  DOS?  prompt.  This  message 
then  prompts  for  the  starting  cylinder  number  of  the  DOS  partition  being  created. 

Enter  the  number  of  the  partition  you 
want  to  make  active . :[»] 

Option  2,  Change  Active  Partition,  has  been  chosen  from  the  main  menu  and  this  message 
prompts  the  user  to  enter  the  number  of  the  partition  that  will  become  the  active  partition. 

Error  loading  operating  system 

An  error  occurred  while  attempting  to  start  the  system  from  the  fixed  disk.  Attempt  to 
restart  the  system.  If  that  fails,  start  the  system  from  a  floppy  disk  and  use  the  SYS  com¬ 
mand  to  copy  a  new  set  of  the  operating-system  files  to  the  fixed  disk. 

Error  reading  flxed  disk 

An  unrecoverable  hardware  error  was  encountered  while  FDISK  was  reading  data  from 
the  fixed  disk.  The  disk  may  require  a  low-level  (hardware)  formatting  operation  before 
FDISK  can  be  used;  this  is  usually  performed  with  a  special  utility  program  provided  by 
the  drive  manufacturer. 
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An  unrecoverable  hardware  error  was  encountered  while  FDISK  was  writing  the  new  par¬ 
tition  control  record  to  the  fixed  disk.  Test  the  fixed  disk  with  hardware  diagnostics  before 
further  use. 

Fixed  disk  already  has  a  DOS  partition. 

The  specified  fixed  disk  already  contains  an  MS-DOS  partition.  Be  sure  that  the  correct 
fixed  disk  has  been  selected  before  proceeding. 

Incorrect  DOS  version 

The  version  of  FDISK  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Invalid  partition  table 

The  fixed  disk’s  partition  table  is  invalid  and  the  operating  system  could  not  be  loaded 
from  the  fixed  disk  during  system  initialization.  Restart  the  computer  using  a  floppy  disk 
and  rerun  FDISK  to  determine  and  correct  the  problem. 

Missing  operating  system 

The  DOS  partition  is  the  active  partition,  but  it  does  not  contain  the  operating  system. 
(This  message  occurs  only  during  system  startup.)  Use  the  SYS  command  to  install  the 
operating  system. 

No  DOS  partition  to  delete. 

The  fixed  disk  does  not  contain  an  MS-DOS  partition. 

No  fixed  disks  present 

FDISK  cannot  detect  a  fixed  disk  in  the  system.  This  may  reflect  a  hardware  problem  with 
the  fixed  disk  or  its  controller. 

No  partitions  defined. 

This  informational  message  is  displayed  after  the  user  has  chosen  option  4,  Display 
Partition  Data,  to  indicate  that  no  partitions  are  currently  defined. 

No  partitions  to  make  active 

The  fixed  disk  has  not  been  previously  partitioned  using  FDISK;  therefore,  an  active  parti¬ 
tion  cannot  be  selected. 

No  space  for  anifif  cylinder  partition. 

The  fixed  disk  does  not  have  enough  free  cylinders  to  create  the  desired  partition. 

No  space  to  create  a  DOS  partition. 

The  fixed  disk  does  not  have  enough  free  cylinders  to  create  an  MS-DOS  partition. 

Partition  n  is  already  active 

The  selected  partition  is  already  active  (bootable);  therefore,  no  action  was  taken. 

Partition  If  made  active 

This  informational  message  indicates  that  the  selected  partition  has  been  made  the  active 
partition. 
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System  will  now  restart 
Insert  DOS  diskette  in  drive  A: 

Press  any  key  when  ready. . . 

The  DOS  partition  has  successfully  been  created.  Strike  any  key  and  the  system  will  restart 
from  the  disk  in  drive  A. 

The  current  active  partition  is  if. 

This  informational  message  indicates  which  partition  is  currently  bootable. 

The  table  partition  can’t  be  made  active. 

The  master  partition  record  cannot  be  made  bootable. 

Total  disk  space  is  nnn  cylinders. 

This  informational  message  indicates  the  total  number  of  cylinders  on  the  fixed  disk. 

Total  disk  space  is  nnn  cylinders. 

Maximum  available  space  is  nnn 
cylinders  atn . 

The  user  has  responded  N  to  the  Do  you  wish  to  use  the  entire  fixed  disk for  DOS?  prompt 
and  this  informational  message  indicates  how  much  space  is  available  for  the  DOS 
partition. 

Warning:  Data  in  the  DOS  partition 
will  be  lost.  Doyou  wish  to 
continue . ?[N] 

If  the  MS-DOS  partition  is  deleted,  all  files  within  the  partition  are  lost.  Be  sure  that  the 
files  are  backed  up  to  another  disk  before  proceeding.  Respond  with  N  to  return  to  the 
FDISK  main  menu;  respond  with  Y  to  delete  the  DOS  partition  and  lose  any  files  within  it. 
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FIND  2.0  and  later 

Find  Character  String  External 

Purpose 

Searches  the  character  stream  from  a  file  or  from  standard  input  for  a  string  and  displays 
any  lines  that  contain  the  string  on  standard  output. 

Syntax 

FIND  [/C]  [/N]  [/V]  "'string'  [[drive'][path]filenuine]  [[drive‘][path] filename . . .] 
where: 

string  is  the  character  string  to  be  searched  for,  always  enclosed  in  quotation  marks; 
case  is  significant. 

filename  is  the  name  of  the  file  to  be  searched,  optionally  preceded  by  a  drive  and/or 
path;  wildcard  characters  are  not  permitted. 

/C  displays  only  the  count  of  the  lines  containing  string. 

/N  includes  the  relative  line  number  with  each  line. 

/V  displays  only  those  lines  that  do  not  contain  string. 

Description 

The  FIND  command  searches  for  all  occurrences  of  a  specified  string  in  one  or  more  files 
(or  from  standard  input).  Normally,  FIND  copies  each  line  in  which  the  string  is  found  to 
standard  output,  which  defaults  to  the  video  display  but  can  be  redirected  to  a  file  or 
another  character  device  or  can  be  piped  to  another  program. 

The  string  to  be  searched  for  must  be  enclosed  in  quotation  marks.  If  the  search  string  it¬ 
self  contains  sets  of  quotation  marks,  each  of  those  sets  of  quotation  marks  must  be  sur¬ 
rounded  by  an  additional  set  of  quotation  marks.  FIND’s  string  search  is  case  sensitive. 

The  search  string  can  be  followed  by  the  names  of  one  or  more  source  files;  these  file¬ 
names  cannot  include  wildcards.  If  no  filename  is  supplied,  FIND  reads  lines  from  stan¬ 
dard  input;  unless  input  has  been  redirected  from  a  file  or  from  the  output  of  another 
program,  this  means  that  FIND  reads  input  from  the  keyboard.  (Keyboard  input  is  termi¬ 
nated  by  pressing  Ctrl-Z  or  F6  followed  by  Enter.) 

The  /C  switch  counts  the  total  number  of  lines  in  which  the  string  appears  and  sends  the 
count,  rather  than  the  lines  themselves,  to  standard  output.  If  the  /C  switch  is  used  with  /V, 
only  the  total  count  of  lines  that  do  not  contain  the  specified  search  string  is  displayed.  If 
both  /C  and  /N  are  included  in  the  same  FIND  command,  the  /N  is  ignored. 

The  /N  switch  includes  a  relative  line  number  with  each  line  sent  to  standard  output.  This 
is  especially  helpful  when  the  output  of  FIND  is  to  be  used  as  a  guide  to  editing  the  files. 

The  /V  switch  reverses  the  action  of  FIND  so  that  it  copies  to  standard  output  all  lines  that 
do  not  include  the  specified  string. 
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Examples 

To  find  and  display  all  lines  in  the  files  BREAK.ASM,  TALK.ASM,  and  SHELL. ASM  that  con¬ 
tain  the  string  es:,  type 

OFIND  ”es:”  BREAK.ASM  TALK.ASM  SHELL. ASM  <Enter> 

To  find  and  display  all  lines  in  the  file  STORY.TXT  that  contain  the  string  he  said 
type 

OFIND  "he  said  ""no"””  STORY.TXT  <Enter> 

To  search  the  file  \SOURCE\MENUMGR.ASM  on  the  current  drive  and  display  all  lines 
that  do  not  contain  the  string  Error,  type 

OFIND  /V  "Error”  \ SOURCE \MENUMGR. ASM  <Enter> 

To  obtain  a  listing  on  the  printer  of  the  lines  in  the  file  SHELL. ASM  in  the  current  directory 
of  the  current  drive  that  contain  the  string  proc,  including  line  numbers,  type 

OFIND  /N  "proc”  SHELL. ASM  >  PRN  <Enter> 

To  search  for  all  lines  that  contain  two  strings,  pipe  the  output  of  one  FIND  command  to 
be  the  input  of  another.  For  example,  to  find  only  those  lines  in  the  file  MENUMGR.ASM  in 
the  current  directory  of  the  current  drive  that  contain  both  the  strings  MOV  and  AX,  type 

OFIND  "MOV"  MENUMGR.ASM  1  FIND  "AX”  <Enter> 

Messages 

- filename 

This  informational  message  gives  the  name  of  the  file  that  is  currently  being  searched. 

FIND:  Access  denied 

The  specified  file  is  locked  or  being  accessed  by  another  application. 

FIND:  File  not  found  filename 

The  specified  file  does  not  exist  or  the  path  or  drive  is  not  correct. 

FIND:  Invalid  number  of  parameters 

The  command  line  did  not  include  a  search  string. 

FIND:  Invalid  Parameter  optidif 

The  command  line  included  an  invalid  switch. 

FIND:  Read  error  in  filename 

A  disk  error  occurred  during  processing  of  the  specified  file. 

FIND:  Syntax  error 

The  command  line  included  an  invalid  search  string.  The  string  must  be  enclosed  in 
quotation  marks. 

Incorrect  DOS  version 

The  version  of  FIND  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 
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1.0  and  later 


Initialize  Disk 


External  No  Net 


Purpose 

Prepares  a  disk  for  use  by  initializing  the  directory  and  file  allocation  table  (FAT). 

Syntax 

FORMAT  [drive-]  [/S]  (versions  1.x) 

or 

FORMAT  [drive]  [/O]  [/V]  [/S]  (versions  2.0-3.1) 

or 

FORMAT  drive:  [/I]  [/4]  [/8]  [/N: n]  [/Tin]  [/V]  [/S]  (version  3.2) 

or 

FORMAT  drive:  [/I]  [/B]  [/N:  n]  [/T: n]  (version  3.2) 

where: 

drive  is  the  location  of  the  disk  to  be  formatted. 

/I  formats  a  single-sided  disk  in  a  double-sided  disk  drive. 

/4  formats  a  standard  double-sided,  double-density  disk  (360  KB)  on  a  quad- 

density  disk  drive. 

/8  formats  a  disk  with  8  sectors  per  track. 

/B  formats  a  disk  with  8  sectors  per  track  and  preallocates  space  for  the  hidden 

operating-system  files. 

/N:  n  formats  a  disk  with  n  sectors  per  track. 

/O  formats  a  disk  that  is  compatible  with  PC-DOS  versions  1.x. 

/S  creates  a  system  (bootable)  disk;  for  most  implementations  of  FORMAT,  this 

must  be  the  last  switch  in  the  command  line. 

/T:  n  formats  a  disk  with  n  tracks. 

/V  allows  a  volume  label  to  be  assigned  to  the  disk  after  formatting. 

Note:  Each  OEM  determines  which  switches  will  be  supported  by  the  FORMAT  utility  in¬ 
cluded  with  the  versions  of  MS-DOS  sold  with  its  computers. 

Description 

The  FORMAT  command  effectively  erases  any  existing  data  on  a  disk  and  creates  a  new 
root  directory  and  file  allocation  table.  Each  sector  of  the  disk  is  checked  for  defects  and 
unusable  sectors  are  marked  so  that  they  will  not  be  assigned  to  files. 
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If  the  drive  parameter  is  not  supplied,  the  current  or  default  drive  is  formatted.  (A  drive 
letter  must  be  specified  with  version  3.2.)  With  versions  3.0  and  later,  the  FORMAT  pro¬ 
gram  displays  a  warning  if  the  drive  to  be  formatted  is  a  fixed  disk  and  asks  for  confirma¬ 
tion  before  continuing. 

When  the  formatting  operation  is  complete,  FORMAT  displays  the  total  amount  of  disk 
space,  the  number  of  bytes  lost  to  defective  sectors,  the  space  reserved  for  or  occupied  by 
the  hidden  operating-system  files  (if  the  /B  or  /S  switch  was  used),  and  the  remaining  free 
disk  space.  If  a  floppy  disk  was  formatted,  FORMAT  then  prompts  the  user  to  select  be¬ 
tween  formatting  another  disk  and  returning  to  MS-DOS. 

Normally,  the  type  of  disk  drive  determines  the  format  that  is  given  to  a  disk.  For  example, 
if  a  disk  is  formatted  in  a  standard  double-sided,  double-density  drive,  the  format  defaults 
to  double-sided,  40  tracks  per  side,  9  sectors  per  track.  The  version-specific  default  formats 
are  9  or  15  sectors  per  track  with  versions  3.0  and  later,  depending  on  the  drive  type;  9  sec¬ 
tors  per  track  with  versions  2.x;  and  8  sectors  per  track  with  versions  1.x.  The  /I,  /4,  /8, 

/N:  w,  and  /T:  w  switches  can  be  used  to  override  the  default  format  in  some  cases.  (Not  all 
combinations  of  /N:  n  and  /T:  n  are  supported  on  all  hardware.) 

Note:  A  disk  formatted  with  the  /4  switch  might  not  be  reliably  read  on  a  single-  or  double¬ 
sided  double-density  drive. 

The  /S  switch  creates  a  system  (bootable)  disk  that  contains  a  copy  of  the  operating 
system.  After  the  format  operation  is  complete,  the  two  hidden  files  lO.SYS  and 
MSDOS.SYS  (or  IBMBIO.COM  and  IBMDOS.COM  in  PC-DOS)  and  the  nonhidden  file 
COMMAND.COM  are  copied  to  the  newly  formatted  disk.  Most  implementations  of 
FORMAT  require  that  the  /S  switch,  if  used,  be  the  last  switch  in  the  command  line. 

The  /V  switch  allows  a  volume  label  to  be  assigned  to  the  new  disk.  After  formatting  is 
complete,  FORMAT  prompts  the  user  for  a  volume  name,  which  can  be  as  many  as  11  char¬ 
acters.  (The  characters  ♦?/!.,;:  +  =  <>[]  and  tab  are  not  permitted  in  a  volume  label.) 
Volume  labels  are  displayed  by  the  DIR,  CHKDSK,  TREE,  and  VOL  commands  and,  with 
MS-DOS  versions  3.1  and  later  and  PC-DOS  versions  3.0  and  later,  can  be  modified  with  the 
LABEL  command  after  the  disk  has  been  formatted. 

The  /O  switch  causes  FORMAT  to  write  an  0E5H  byte  at  the  start  of  each  directory  entry  so 
that  the  resulting  disk  is  compatible  with  MS-DOS  and  PC-DOS  versions  1.x. 

The  /B  switch  formats  a  disk  for  8  sectors  per  track  and  reserves  room  on  the  disk  for  the 
operating-system  files.  The  operating  system  can  then  be  transferred  to  the  disk  with  the 
SYS  command  to  make  the  disk  bootable.  The  /B  switch  cannot  be  used  in  the  same 
FORMAT  command  line  as  the  /V  or  /S  switch. 

Warning:  Disks  in  drives  affected  by  an  ASSIGN,  JOIN,  or  SUBST  command  should  not  be 
formatted.  Disks  cannot  be  formatted  over  a  network. 
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Return  Codes 

0  The  FORMAT  operation  was  successful. 

3  The  program  was  terminated  by  entry  of  a  Ctrl-C  or  Ctrl-Break. 

4  The  program  was  terminated  because  of  a  fatal  system  error  (any  error  other  than  0, 3, 
or  5). 

5  The  program  was  terminated  by  an  N  response  to  the  fixed-disk  prompt  Proceed  with 
FORMAT(Y/N)? 

Note:  Return  codes  are  available  with  MS-DOS  version  3.2. 

Examples 

To  format  the  disk  in  drive  B,  type 

OFORMAT  B:  <Enter> 

In  response,  FORMAT  displays  the  following  message: 

Insert  new  diskette  for  drive  B: 
and  strike  ENTER  when  ready 

With  versions  earlier  than  3.2,  FORMAT  then  displays  the  message 

Formatting  .  .  . 

after  the  Enter  key  is  pressed,  to  show  that  the  formatting  operation  is  in  progress.  With 
version  3.2,  FORMAT  displays  the  message 

Head:  n  Cylinder;  nn 

instead,  to  show  the  progress  of  the  formatting  operation.  With  all  versions,  FORMAT  dis¬ 
plays  the  following  messages  if  the  formatting  operation  is  successful: 

Format  complete 

362496  bytes  total  disk  space 
362496  bytes  available  on  disk 

Format  another  (Y/N) ? 

The  byte  values  may  vary  depending  on  the  drive  type  or  the  switches  used  in  the  com¬ 
mand  line.  If  bad  sectors  were  encountered  during  the  format  operation,  FORMAT  also 
displays  the  number  of  bytes  in  bad  sectors. 

Note:  The  Format  complete  message  overwrites  the  head/cylinder  status  line  but  is  ap¬ 
pended  to  the  Formatting  . . .  status  line. 

To  format  and  assign  a  volume  label  to  the  disk  in  drive  B,  type 

OFORMAT  B:  /V  <Enter> 

After  the  usual  formatting  messages,  FORMAT  prompts  as  follows: 

Volume  label  (11  characters,  ENTER  for  none)  ? 
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The  user  can  then  enter  a  volume  name  of  as  many  as  11  characters  (except  ♦?/!.,;:  +  = 
<>  [  ]  or  tab),  followed  by  a  press  of  the  Enter  key. 

To  format  the  disk  in  drive  B  and  make  it  a  system  (bootable)  disk,  type 

OFORMAT  B:  /S  <Enter> 

FORMAT  initializes  the  disk  in  the  usual  manner  and  then  copies  the  two  files  containing 
the  operating  system  (lO.SYS  and  MSDOS.SYS  or  IBMBIO.COM  and  IBMDOS.COM)  and 
the  file  COMMAND.COM  onto  the  disk.  When  the  formatting  operation  is  completed  on  a 
360  KB  floppy  disk,  the  following  messages  appear: 

Format  complete 
System  transferred 

362496  bytes  total  disk  space 
62464  bytes  used  by  system 
300032  bytes  available  on  disk 

Format  another  (Y/N) ? 

The  number  of  bytes  used  by  the  system  will  vary  with  the  version  of  MS-DOS  in  use. 

Messages 

If  bytes  total  disk  space 
If  bytes  used  by  system 
If  bytes  in  bad  sectors 
If  bytes  available  on  disk 

When  formatting  is  complete,  FORMAT  displays  this  message  with  information  about 
space  available  on  the  disk.  The  bytes  used  by  system  line  will  not  appear  if  the  /S  switch 
was  not  specified;  the  bytes  in  bad  sectors  line  will  not  appear  if  no  bad  sectors  were 
found. 

Attempted  write-protect  violation 

The  disk  to  be  formatted  is  write  protected.  Remove  the  write-protect  tab  and  respond 
with  a  F  to  the  Format  another  (Y/N)?  prompt. 

Cannot  find  System  Files 

The  /S  switch  was  used  and  FORMAT  was  unable  to  find  the  necessary  system  files  in  the 
default  drive  or  in  drive  A. 

Cannot  FORMAT  a  Network  drive 

An  attempt  was  made  to  format  a  disk  in  a  drive  that  has  been  assigned  to  a  network. 

Cannot  format  an  ASSlGNed  or  SUBSTed  drive. 

An  attempt  was  made  to  format  a  disk  in  a  drive  affected  by  an  ASSIGN  or  SUBST 
command. 

Disk  unsuitable  for  system  disk 

Defective  sectors  were  detected  on  the  tracks  where  the  operating-system  files  would  nor¬ 
mally  reside  on  a  bootable  disk.  Such  a  disk  should  be  used  only  for  data  files,  if  at  all. 
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Drive  letter  must  be  specified 

A  drive  letter  must  be  specified  when  using  version  3.2. 

Drive  not  ready 

The  floppy-disk  drive  is  empty  or  the  drive  door  is  not  closed. 

Enter  current  Volume  Label  for  drtveXt 

The  specified  drive  is  a  fixed  disk,  so  FORMAT  prompts  the  user  to  enter  the  current 
volume  label  for  verification. 

Error  in  lOCTL  call 

An  internal  system  error  occurred  when  a  pre-version-3.2  block-device  driver  was  used 
with  version  3.2  of  FORMAT. 

Error  reading  partition  table 

FORMAT  was  unable  to  read  the  fixed  disk's  partition  table.  Use  FDISK  on  the  fixed  disk 
and  then  try  the  FORMAT  command  again. 

Error  writing  directory 

FORMAT  was  unable  to  create  a  directory  on  the  disk  it  is  attempting  to  format.  The  disk  is 
defective. 

Error  writing  FAT 

FORMAT  was  unable  to  create  the  FAT  on  the  disk  it  is  attempting  to  format.  The  disk  is 
defective. 

Error  writing  partition  table 

FORMAT  was  unable  to  write  the  fixed  disk’s  partition  table.  Use  FDISK  on  the  fixed  disk 
and  then  try  the  FORMAT  command  again. 

Format  another  (Y/N)? 

At  the  end  of  a  successful  formatting  operation  or  after  a  nonfatal  error,  this  prompt  offers 
the  user  the  opportunity  to  format  another  disk  using  the  same  switches  specified  in  the 
original  FORMAT  command.  Respond  with  Y  to  format  another  disk;  respond  with  N  to 
return  to  MS-DOS. 

Format  complete 

The  formatting  operation  has  ended.  This  message  contains  a  number  of  space  characters 
after  it  and  is  printed  over  the  top  of  the  head/cylinder  status  message,  effectively  erasing 
it. 

Format  failure 

The  formatting  operation  was  not  successful.  (This  message  is  usually  preceded  by 
another  message  telling  the  user  why  the  format  failed.)  This  message  contains  a  number 
of  space  characters  after  it  and  is  printed  over  the  top  of  the  head/cylinder  status  message, 
effectively  erasing  it. 

Format  not  supported  on  drive  Y: 

Device  parameters  that  the  computer  cannot  support  were  specified  in  the  FORMAT  com¬ 
mand  line. 
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Formatting... 

This  informational  message  indicates  that  the  FORMAT  operation  is  in  progress  (versions 
1.0  through  3.1). 

Head:  n  Cylinder:  nn 

This  informational  message  indicates  the  progress  of  the  FORMAT  command  during  the 
formatting  operation  (version  3.2). 

Incorrect  DOS  version 

The  version  of  FORMAT  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insert  DOS  disk  in  drived: 
and  strike  ENTER  when  ready 

The  /S  switch  was  specified  in  the  FORMAT  command  line  and  the  disk  containing  the 
FORMAT  command  does  not  also  contain  the  hidden  system  files. 

Insert  new  diskette  for  drived: 
and  strike  ENTER  when  ready 

This  prompt  allows  the  user  to  change  disks  before  the  FORMAT  operation  continues. 

Insufficient  memory  for  system  transfer 

The  command  line  included  the  /S  switch,  but  available  RAM  is  insufficient  to  hold  the 
system  files  during  the  FORMAT  operation. 

Invalid  characters  in  volume  label 

Certain  characters  (*?/!.,;:  +  =  <>[]  and  tab)  are  not  allowed  in  a  volume  name. 

Invalid  device  parameters  from  device  driver 

The  DEVICE  or  DRIVPARM  device-driver  parameters  in  the  CONFIG.SYS  file  were  incor¬ 
rectly  set  or  the  fixed  disk  specified  in  the  command  line  was  formatted  using  MS-DOS 
versions  2.x  without  first  running  FDISK.  FORMAT  displays  this  message  when  the  number 
of  hidden  sectors  is  not  evenly  divisible  by  the  number  of  sectors  per  track  (meaning  that 
the  partition  does  not  start  on  a  track  boundary). 

Invalid  drive  specification 

The  drive  specified  after  the  FORMAT  command  is  not  a  valid  drive. 

Invalid  media  or  Track  0  bad  -  disk  unusable 

One  of  the  switches  supplied  in  the  command  line  is  not  valid  for  the  drive  containing  the 
disk  to  be  formatted  (for  example,  the  /8  switch  for  a  quad-density  floppy  disk)  or  track  0 
of  the  disk  being  formatted  is  unusable  to  the  point  that  FORMAT  is  unable  to  create  a 
directory  or  file  allocation  table  (FAT). 

Invalid  parameter 

One  of  the  switches  supplied  in  the  command  line  is  not  valid  or  is  not  supported  by  the 
version  of  FORMAT  being  used. 

Invalid  volume  ID 

The  volume  label  entered  in  response  to  the  Enter  current  Volume  Label  for  drive  X: 
prompt  was  not  the  same  as  the  current  volume  label.  Use  the  VOL  command  to  determine 
the  current  volume  label. 
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Non-System  disk  or  disk  error 
Replace  and  strike  any  key  when  ready 

The  command  line  contained  a  /S  or  /B  switch,  but  the  source  disk  does  not  contain  the 
operating-system  files. 

Not  a  block  device 

The  drive  containing  the  disk  to  be  formatted  is  not  recognized  by  MS-DOS  as  a  valid 
block  device. 

Parameters  not  compatible 

Switches  that  cannot  be  used  together  were  specified  in  the  command  line. 

Parameters  not  compatible  with  fixed  disk 

One  of  the  switches  specified  in  the  command  line  is  not  compatible  with  the  specified 
drive. 

Parameters  not  supported 

One  of  the  parameters  specified  in  the  command  line  is  not  supported  by  the  version  of 
FORMAT  being  used. 

Parameters  not  Supported  by  Drive 

The  device  driver  for  the  specified  drive  does  not  support  generic  lOCTL  function 
requests. 

Re-insert  diskette  for  drive  Jf: 

This  message  prompts  the  user  to  reinsert  the  disk  being  formatted  into  the  specified 
drive. 

System  transferred 

The  system  files  lO.SYS  and  MSDOS.SYS  (or  IBMBIO.COM  and  IBMDOS.COM  in  PC-DOS) 
and  the  file  COMMAND.COM  have  been  successfully  transferred  to  the  newly  formatted 
disk. 

Too  many  open  files 

FORMAT  was  unable  to  write  the  volume  label  because  insufficient  system  file  handles 
were  available.  Increase  the  value  of  FILES  in  the  CONFIG.SYS  file. 

Volume  label  (11  characters,  ENTER  for  none)? 

After  formatting  a  disk  with  the  /V  option,  FORMAT  offers  the  user  the  opportunity  to  en¬ 
ter  a  volume  label  for  the  disk. 

Unable  to  write  BOOT 

The  first  track  of  the  disk  or  MS-DOS  partition  is  bad  and  cannot  be  made  bootable. 

WARNING,  ALL  DATA  ON  NON  REMOVABLE  DISK 
DRIVE  JIT:  WILL  BE  LOST! 

Proceed  with  Format  (Y/N)? 

If  a  fixed  disk  is  specified  as  the  disk  to  be  formatted,  FORMAT  warns  the  user  and  gives 
the  opportunity  to  cancel  the  FORMAT  command  (versions  3.0  and  later). 
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GRAFTABL  3.0  and  later 

Load  Graphics  Character  Set  External 


Purpose 

Installs  a  RAM-resident  table  of  bitmaps  that  defines  the  screen  appearance  of  character 
codes  128  through  255  in  graphics  mode. 

Syntax 

GRAFTABL 

Description 

On  IBM  PCs  and  compatibles  in  graphics  display  modes,  the  video-display  BIOS  routines 
(Interrupt  lOH)  display  characters  by  writing  bitmapped  matrices  of  dots  to  the  display. 
The  dot  pattern  of  each  screen  character’s  matrix  is  defined  by  an  entry  in  a  table  of  bit¬ 
maps.  The  table  of  bitmaps  for  the  regular  ASCII  characters,  coded  0  through  7FH  (0-127), 
is  permanently  located  in  ROM  and  is  always  available  for  use  by  the  system’s  video  driver. 
The  GRAFTABL  utility  contains  a  similar  table  of  bitmaps  for  the  upper  (extended)  charac¬ 
ters,  coded  80H  through  OFFH  (128-255).  The  GRAFTABL  command  loads  this  table  into 
RAM  and  places  the  address  of  the  table  in  the  vector  for  Interrupt  IFH. 

The  GRAFTABL  command  is  not  needed  for  the  IBM  PCjr  or  for  an  enhanced  graphics 
adapter;  their  ROM  BIOS  already  contains  tables  of  bitmaps  for  the  extended  character  set. 

GRAFTABL  is  a  terminate-and-stay-resident  (TSR)  program;  therefore,  its  installation 
reduces  the  amount  of  RAM  available  for  use  by  application  programs. 

The  GRAFTABL  command  can  be  executed  only  once  after  the  computer  has  been  turned 
on  or  restarted.  An  attempt  to  execute  it  again  will  result  in  an  informational  message  stat¬ 
ing  that  the  graphics  characters  are  already  loaded. 

Example 

To  load  the  table  of  bitmaps  for  characters  80H  through  OFFH  (128-255)  for  use  in  graphics 
mode,  type 

OGRAFTABL  <Enter> 

Messages 

DOS  2.0  or  later  required 

GRAFTABL  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Graphics  characters  already  loaded 

The  GRAFTABL  command  has  already  been  executed  since  the  system  was  turned  on  or 
restarted. 
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Graphics  characters  loaded 

The  table  of  bitmaps  has  been  successfully  loaded  into  RAM  and  the  interrupt  vector  that 
points  to  the  table  has  been  initialized. 

Incorrect  DOS  version 

The  version  of  GRAFTABL  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 
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GRAPHICS  32 

Load  Graphics  Screen-Dump  Program  External 

Purpose 

Installs  a  resident  program  that  can  dump  screen  contents  to  the  printer  in  graphics  mode. 
This  command  is  also  available  with  PC-DOS  versions  2.0  and  later. 

Syntax 

GRAPHICS  (PC-DOS  2.x) 

or 

GRAPHICS  [printer]  [/B]  [/R]  (PC-DOS  3.0  and  above) 

or 

GRAPHICS  [printer]  [/B]  [/C]  [/F]  [/P  port]  [/R]  (MS-DOS  3.2) 

where: 

printer  is  the  type  of  printer  to  be  supported,  from  the  following  list: 

COLORl  IBM  Personal  Computer  Color  Printer  with  black  ribbon 

COLOR4  IBM  Personal  Computer  Color  Printer  with  red-green-blue- 

black  (RGB)  ribbon 

COLORS  IBM  Personal  Computer  Color  Printer  with  cyan-magenta- 

yellow-black  (CMY)  ribbon 

COMPACT  IBM  Personal  Computer  Compact  Printer 
GRAPHICS  IBM  Personal  Computer  Graphics  Printer  or  compatible 

(the  default) 

/B  prints  the  background  in  color;  valid  only  with  the  COLOR4  and  COLORS 

printers. 

/C  centers  the  printout  on  the  page. 

/F  flips  (rotates)  the  printout  90  degrees. 

/P port  specifies  which  port  the  printer  is  attached  to  (1-3,  where  1  =  LPTl,  2  =  LPT2, 
and  3  =  LPT3). 

/R  prints  the  image  as  it  appears  on  the  screen  (white  characters  on  a  black  back¬ 

ground)  rather  than  reversed  (the  default,  black  characters  on  a  white 
background). 

Description 

The  default  system  routine  for  dumping  the  screen  to  the  printer  (invoked  by  Shift-PrtSc) 
cannot  interpret  the  display  in  graphics  modes.  The  GRAPHICS  command  loads  a  more 
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sophisticated  routine  that  can  dump  CGA-compatible  graphics  displays  to  several  models 
of  IBM  graphics  printers  or  compatibles.The  GRAPHICS  command  is  not  compatible  with 
the  Hercules  monochrome  graphics  card  or  with  an  enhanced  graphics  adapter  in  its  en¬ 
hanced  display  modes. 

If  the  display  is  in  640  x  200  graphics  mode,  the  screen  dump  is  printed  sideways  (rotated 
90  degrees).  A  320  x  200  graphic  can  be  rotated  manually  by  specifying  the  /F  switch  in 
the  command  line;  however,  the  image  will  be  elongated  horizontally.  A  rotated  image  is 
printed  along  the  left  side  of  the  page,  which  is  actually  the  top  of  the  page  in  terms  of  im¬ 
age  orientation.  The  /C  option  can  be  used  to  center  a  rotated  320  x  200  image  on  the 
page. 

When  used  with  a  printer  with  a  black  ribbon,  GRAPHICS  produces  screen  dumps  with  as 
many  as  four  shades  of  gray  to  represent  the  colors.  When  used  with  a  printer  with  a  color 
ribbon  (type  COLOR4  or  COLORS),  GRAPHICS  prints  all  the  colors  except  the  background 
color.  With  printer  types  COLOR4  and  COLORS,  the  /B  switch  can  be  used  to  print  the 
background  color  also. 

Ordinarily,  the  screen  image  being  dumped  is  reversed  from  its  appearance  on  the  screen; 
that  is,  the  light  areas  on  the  screen  are  dark  on  the  printed  output  and  vice  versa.  The  /R 
switch  produces  a  screen  dump  that  is  not  reversed  in  this  manner. 

If  the  printer  parameter  is  not  included  in  the  command  line,  the  GRAPHICS  program 
assumes  an  IBM  Personal  Computer  Graphics  Printer  or  compatible. 

If  two  or  more  printers  are  attached  to  the  system,  the  /P  switch  can  be  used  to  specify 
which  printer  GRAPHICS  should  use. 

The  GRAPHICS  command  is  a  terminate-and-stay-resident  (TSR)  program;  therefore,  its 
installation  reduces  the  amount  of  RAM  available  for  use  by  application  programs. 

Examples 

To  load  the  graphics  printing  program  for  use  with  an  IBM  Personal  Computer  Graphics 
Printer  or  compatible  connected  to  LPT2,  type 

OGRAPHICS  /P  2  <Enter> 

Note:  A  tab,  a  semicolon  character  (;),  or  an  equal  sign  (=)  can  be  used  between  the  /P  and 
the  port  number  instead  of  a  space. 

To  load  the  graphics  printing  program  for  use  with  the  IBM  Personal  Computer  Color  Prin¬ 
ter  with  an  RGB  ribbon  and  specify  that  the  background  color  be  printed,  type 

C>GRAPHICS  C0L0R4  /B  <Enter> 

To  load  the  graphics  printing  program  for  use  with  the  IBM  Personal  Computer  Compact 
Printer  and  specify  that  the  images  be  printed  sideways  and  centered  on  the  page,  type 

C>GRAPHICS  COMPACT  /F  /C  <Enter> 
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Messages 

DOS  2.0  or  later  required 

GRAPHICS  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Incorrect  DOS  version  ^ 

The  version  of  GRAPHICS  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Unrecognized  printer 

The  printer  type  specified  in  the  command  line  is  invalid  or  the  printer  is  not  supported. 

Unrecognized  printer  port 

The  port  specified  with  the  /P  switch  is  not  a  number  in  the  range  1  through  3  or  an  invalid 
separator  character  was  used. 
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Join  Disk  to  Directory 


3.0  and  later 
External  No  Net 


Purpose 

Joins  the  directory  structure  of  a  disk  drive  to  a  subdirectory  on  another  drive. 

Syntax 

JOIN  [drivel:  drive2:path] 
or 

JOIN  drivel:  /D 
where: 
drivel 

drive2:path 
/D 

Description 

The  JOIN  command  allows  the  directory  structure  of  a  disk  in  one  drive  to  be  joined,  or 
spliced,  into  an  empty  subdirectory  of  a  disk  in  another  drive.  After  a  JOIN,  the  entire 
directory  structure  of  the  disk  in  drivel,  starting  at  the  root,  together  with  all  the  files  that 
it  contains,  appears  to  be  the  directory  structure  of  the  specified  subdirectory  on  the  disk 
in  drive2\  the  drive  letter  for  drivel  is  no  longer  available.  If  the  directory  at  the  end  of  the 
path  on  drive2  already  exists,  it  must  not  contain  any  files;  if  it  does  not  exist,  JOIN  will 
attempt  to  create  it. 

The  current  directory  status  of  drivel  has  no  effect  on  the  JOIN  operation.  Regardless  of 
which  directory  or  subdirectory  is  active  when  the  JOIN  command  is  entered,  the  entire 
directory  structure,  including  the  root  directory,  is  joined  to  the  subdirectory  on  the  disk  in 
drive2. 

The  /D  switch  cancels  any  previous  JOIN  command  for  a  specific  drive. 

If  the  JOIN  command  is  entered  without  parameters,  it  displays  a  list  of  all  joins  currently 
in  effect. 

Warning:  The  JOIN  command  should  not  be  used  on  drives  affected  by  a  SUBST  or 
ASSIGN  command.  Similarly,  the  BACKUP,  RESTORE,  FORMAT,  DISKCOPY,  and 
DISKCOMP  commands  should  not  be  used  on  drives  affected  by  the  JOIN  command. 
Drives  that  have  been  redirected  over  a  network  cannot  be  joined. 


is  the  drive  whose  directory  structure  will  be  joined  to  a  subdirectory  of 
another  drive. 

is  the  drive  and  directory  that  will  be  used  to  reference  files  on  drivel. 
cancels  the  effect  of  a  previous  JOIN  command  on  drivel. 
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Examples 

To  join  drive  B  to  the  subdirectory  \  DRIVED  on  drive  C,  type 

C>JOIN  B:  C:\DRIVEB  <Enter> 

A  subsequent  JOIN  command  without  parameters  displays 

B:  =>  C:\DRIVEB 

To  then  list  the  files  in  the  root  directory  of  the  disk  in  drive  B,  type 

C>DIR  C:\DRIVEB  <Enter> 

To  cancel  a  previous  JOIN  command  affecting  drive  B,  type 

C>JOIN  B:  /D  <Enter> 

Messages 

Cannot  JOIN  a  network  drive 

A  drive  assigned  to  a  network  cannot  be  joined  to  another  drive. 

Directory  not  empty 

A  drive  cannot  be  joined  to  a  directory  that  already  contains  files. 

DOS  2.0  or  later  required 

JOIN  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Incorrect  DOS  version 

The  version  of  JOIN  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Incorrect  number  of  parameters 

There  were  missing,  extra,  or  incorrect  parameters  in  the  command  line. 

Invalid  parameter 

A  drive  cannot  be  joined  to  the  root  directory  of  any  drive. 

Not  enough  memory 

The  available  system  memory  is  insufficient  for  MS-DOS  to  run  the  JOIN  command. 
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Define  Keyboard 


3.2 

External 


Purpose 

Installs  a  table  that  defines  the  translation  of  keys  to  the  extended  character  codes,  replac¬ 
ing  the  default  table  in  the  ROM  BIOS.  This  command  is  included  with  PC-DOS  beginning 
with  version  3.0. 

Syntax 

KEYBxx 

where: 

XX  is  a  code  that  selects  a  keyboard  configuration: 

DV  Dvorak  keyboard  (MS-DOS  only) 

FR  French 
GR  German 
IT  Italian 

SP  European  Spanish 

UK  United  Kingdom  English 

Note:  KEYBxa:  is  hardware  dependent;  therefore,  implementation  of  this  command  may 
vary  for  different  OEM  versions  of  MS-DOS. 

Description 

The  KEYBxx  utility  configures  the  keyboard  for  use  with  a  language  other  than  United 
States  English,  making  available  special  characters  that  are  appropriate  for  the  specified 
country’s  language  and  currency.  These  special  characters  are  represented  by  the  ex¬ 
tended  character  codes  (128-255)  that  correspond  to  the  characters  implemented  on  the 
OEM’s  display  adapter.  (Both  the  KEYBxx  and  the  GRAFTABL  commands  must  be  used 
to  make  these  characters  available  in  graphics  modes  on  a  color/graphics  adapter.) 

After  KEYBxx  is  loaded,  special  accented  characters  not  part  of  the  language  in  use  are 
also  available  through  the  use  of  dead  keys — keys  that  are  pressed  and  released  before 
the  letter  key  is  pressed.  The  following  dead  keys  are  available  on  a  United  States  English 
keyboard  for  an  IBM  PC,  PC/XT,  PC/AT,  or  strict  compatible: 
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Keyboard 

Dead 

Resulting 

Program 

Key 

Accent 

KEYBGR  (Germany) 

+ 

KEYBFR  (France) 

[ 

/ 

KEYBSP  (Spain) 

1 

t 

] 

1 

KEYBUK  (United  Kingdom) 

1 

) 

Not  supported 

KEYBIT  (Italy) 

Not  supported 

The  dead-key  combinations  supported  are 

Keyboard 

Combinations 

Program 

Supported 

Germany  aeEiouaeiou 

France  aAeioOuUyaeiou 

Spain  aAeioOuUyaeEiou 

aeiduaeiou 


United  Kingdom 
Italy 


Dead  key  not  supported 
Dead  key  not  supported 


On  an  IBM  PC,  PC/XT,  PC/AT,  or  strict  compatible,  the  key  sequence  Ctrl-Alt-Fl  can  be 
used  at  any  time  to  return  the  keyboard  to  the  default  (United  States  English)  configura¬ 
tion;  the  sequence  Ctrl-Alt-F2  then  returns  the  keyboard  to  the  selected  configuration. 

KEYB:v:\r  should  be  loaded  only  once  during  an  MS-DOS  session;  the  computer  should  be 
restarted  if  KEYBxx  is  loaded  for  use  with  a  different  language. 

KEYBxjc  is  a  terminate-and-stay-resident  (TSR)  utility  and  therefore  reduces  the  amount 
of  memory  available  to  transient  application  programs  (by  approximately  2  KB).  The  only 
way  to  reclaim  this  memory  is  to  restart  the  system. 

Example 

To  configure  the  keyboard  for  Germany,  type 

OKEYBGR  <Enter> 
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Messages 

Bad  command  or  filename 

The  selected  keyboard  does  not  exist  or  the  program  that  configures  the  keyboard  is  not 
present  on  the  disk. 

Incorrect  DOS  version 

The  version  of  KEYBxx  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 
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LABEL 

Modify  Volume  Label 


3.1  and  later 
External  No  Net 


Purpose 

Adds,  alters,  or  deletes  a  volume  label  on  a  disk.  This  command  is  included  with  PC-DOS 
beginning  with  version  3.0. 

Syntax 

LABEL  [drive‘][label\ 
where: 

drive  is  any  valid  disk  drive. 

label  is  a  name  up  to  1 1  characters  long. 

Description 

With  MS-DOS  versions  2.0  and  later,  each  disk  can  have  a  name  called  a  volume  label, 
which  is  implemented  as  a  special  type  of  entry  in  the  disk’s  root  directory.  With  MS-DOS 
versions  2.x,  this  volume  label  can  be  assigned  to  a  disk  only  at  the  time  the  disk  is  format¬ 
ted,  using  the  FORMAT  command’s  /V  switch.  However,  with  PC-DOS  versions  3.0  and 
later  and  MS-DOS  versions  3.1  and  later,  the  volume  label  can  be  added,  modified,  or 
deleted  at  any  time  using  the  LABEL  command.  (A  disk’s  volume  label  can  be  displayed 
with  the  VOL  command;  the  label  is  also  included  as  part  of  the  output  from  the  CHKDSK, 
DIR,  and  TREE  commands.) 

If  a  new  volume  name  is  included  in  the  LABEL  command  line,  the  disk’s  label  is  changed 
immediately.  If  LABEL  is  entered  alone  or  with  only  a  drive  letter,  a  message  is  displayed 
giving  the  current  volume  label  of  the  disk  in  the  specified  drive  (or  the  default  drive,  if  no 
drive  letter  is  given)  and  prompting  the  user  for  a  new  label.  (A  volume  label  can  be  from  1 
to  11  characters;  it  cannot  contain  any  of  the  characters  ♦P/X  !.,;:  +  =  <>[]  or  tab.)  If  no 
new  volume  name  is  supplied  (the  user  did  not  type  a  volume  label  before  pressing  Enter), 
LABEL  prompts  the  user  to  indicate  whether  the  previous  volume  label  should  be  deleted. 
Existing  files  on  the  disk  are  in  no  way  affected  by  the  LABEL  command. 

The  LABEL  command  cannot  be  used  on  a  network  drive.  With  MS-DOS  version  3.2,  the 
LABEL  command  also  cannot  be  used  on  a  disk  in  a  drive  that  is  affected  by  an  ASSIGN  or 
SUBST  command. 

Examples 

To  give  the  volume  label  PAYROLL  to  the  disk  in  drive  B,  type 

C>LABEL  B: PAYROLL  <Enter> 
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Note  that  LABEL  immediately  overwrites  any  existing  volume  label  on  drive  B  with  the 
new  name;  no  warning  of  an  existing  volume  label  is  given. 

To  remove  the  volume  label  LEDGER  from  the  disk  in  drive  A,  type 

OLABEL  A:  <Enter> 

The  LABEL  command  displays 

Volume  in  drive  A  is  LEDGER 

Volume  label  (11  characters,  ENTER  for  none)? 

Press  the  Enter  key  to  receive  the  additional  prompt 

Delete  current  volume  label  (Y/N)? 

Then  respond  with  V  and  Enter  to  remove  the  volume  label  from  the  disk  in  drive  A. 

Messages 

Cannot  LABEL  a  Network  drive 

The  disk  drive  specified  in  the  command  line  cannot  be  a  network  drive. 

Cannot  LABEL  a  SUBSTed  or  ASSIGNed  drive 

The  disk  drive  specified  in  the  command  line  is  currently  affected  by  a  SUBST  or  ASSIGN 
command  (MS-DOS  version  3.2). 

Delete  current  volume  label  (Y/N)? 

No  volume  label  was  entered  in  response  to  the  volume-label  prompt  and  a  volume  label 
already  exists  on  the  disk.  Respond  with  V  to  delete  the  current  label;  respond  with  N  to 
terminate  the  command. 

Incorrect  DOS  version 

The  version  of  LABEL  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Invalid  characters  in  volume  label 

The  characters  *?/\  !.,;:  +  =  <>[]  and  tab  cannot  be  part  of  a  volume  label. 

Invalid  drive  specification 

The  drive  specified  in  the  command  line  is  not  valid  or  does  not  exist  in  the  system. 

No  room  in  root  directory 

The  root  directory  of  the  disk  in  the  designated  drive  is  full  and  a  volume  label  cannot  be 
added.  Delete  a  file  or  subdirectory  from  the  root  directory  to  make  room  for  the  label. 

Too  many  files  open 

LABEL  was  unable  to  write  the  volume  label  because  no  system  file  handles  were  avail¬ 
able.  Increase  the  value  of  FILES  in  the  CONFIG.SYS  file. 
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Volume  indriveX  has  no  label 

Volume  label  (11  characters,  ENTER  for  none)? 

or 

Volume  in  driveX  is  xxxxxxxxxxx 
Volume  label  (11  characters,  ENTER  for  none)? 

This  informational  message  informs  the  user  of  the  current  volume  label  and  prompts  the 
user  to  add,  change,  or  delete  it. 
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MKDIRorMD  2.0  and  later 

Make  Directory  Internal 


Purpose 

Creates  a  new  directory. 

Syntax 

MKDIR  [drive'][path\  new^directory 
or 

MD  [drive][pathi\new_directory 
where: 

new^directory  is  a  valid  directory  name,  optionally  preceded  by  an  existing  path 

and/or  a  disk  drive. 

Description 

The  MKDIR  command  creates  a  directory,  adding  a  branch  to  the  hierarchical  directory 
structure  of  the  disk.  If  the  name  of  the  new  directory  is  preceded  by  a  path,  indicating 
that  the  new  directory  is  to  be  a  subdirectory  of  that  path,  the  specified  path  must  already 
exist. 

If  new^directory  is  not  preceded  by  an  existing  path  or  a  backslash  character  (\),  it  is 
presumed  to  be  relative  to  the  current  directory.  If  new^directory  is  preceded  by  a  back¬ 
slash  alone,  the  directory  created  will  be  a  subdirectory  of  the  root  directory,  regardless  of 
the  current  directory.  The  length  of  the  full  path  (including  new^director^  must  not  ex¬ 
ceed  63  characters. 

Warning:  The  MKDIR  command  should  not  be  used  to  create  new  directories  on  drives 
affected  by  an  ASSIGN,  JOIN,  or  SUBST  command. 

Examples 

To  create  a  directory  named  SOURCE  in  the  current  directory  of  the  disk  in  the  current 
drive,  type 

OMKDIR  SOURCE  <Enter> 

or 

OMD  SOURCE  <Enter> 
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To  create  a  directory  named  LETTERS  in  the  existing  directory  named  WORD  (which  is  a 
subdirectory  of  the  root  directory)  on  the  disk  in  drive  D,  type 

OMKDIR  D:\WORD\LETTERS  <Enter> 

or 

OMD  D:\WORD\LETTERS  <Enter> 

Messages 

Invalid  drive  specification 

The  drive  specified  in  the  command  line  is  not  valid  or  does  not  exist  in  the  system. 

Invalid  number  of  parameters 

The  name  of  the  new  directory  was  not  included  in  the  MKDIR  command  line. 

Unable  to  create  directory 

The  specified  directory  cannot  be  created.  This  may  be  caused  by  a  full  disk  (if  the  new 
directory  would  cause  the  current  directory  to  be  extended),  a  full  root  directory  (if  the 
new  directory’s  parent  is  the  root  directory),  the  existence  of  a  file  or  directory  with  the 
same  name,  or  an  invalid  new^directory  name. 
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MODE  3.2 

Configure  Device  External 


Purpose 

The  MODE  command  has  four  distinct  uses: 

•  To  reconfigure  a  printer  attached  to  a  parallel  port  (LPTl,  LPT2,  or  LPT3)  for  printing 
at  80  or  132  characters  per  line,  6  or  8  lines  per  inch,  or  both  (if  the  printer  supports 
these  features).  In  this  form,  MODE  can  also  be  used  to  select  a  parallel  printer  other 
than  the  one  attached  to  LPTl  for  use  as  the  default  printer. 

•  To  select  another  display  or  reconfigure  the  current  display.  Reconfiguration  includes 
changing  between  40-column  and  80-column  display,  changing  between  mono¬ 
chrome  and  color  display,  centering  the  display  on  the  screen,  or  any  combination  of 
these. 

•  To  configure  the  baud  rate,  parity,  and  number  of  databits  and  stop  bits  of  a  serial 
communications  port  (COMl  or  COM2)  for  use  with  a  specific  printer,  modem,  or 
other  serial  device. 

•  To  redirect  printer  output  from  a  parallel  port  to  one  of  the  serial  ports,  so  that  the 
serial  port  becomes  the  system’s  default  printer  port. 

Because  the  syntax  for  each  of  these  uses  of  MODE  is  different,  they  are  discussed 

separately  on  the  following  pages. 

Although  each  form  of  the  MODE  command  can  be  issued  at  the  system  prompt,  MODE 

commands  are  commonly  used  within  the  AUTOEXEC.BAT  file  to  automatically  perform 

any  necessary  reconfiguration  each  time  the  system  is  turned  on  or  restarted. 

The  MODE  command  is  included  with  PC-DOS  beginning  with  version  1.0. 

Message 

Incorrect  Version  of  MODE 

The  version  of  MODE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 
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Configure  Printer  External 


Purpose 

Sets  characteristics  for  IBM-compatible  printers  connected  to  a  parallel  printer  port  (LPTl, 
LPT2,  or  LPT3).  This  form  of  the  MODE  command  is  included  with  PC-DOS  beginning 
with  version  1.0. 

Syntax 

MODE  LPTn[:][cp/]  [,[/p/][,P]] 
where: 

LPT n  is  the  parallel  printer  port  («  =  1, 2,  or  3). 

cpl  is  the  number  of  characters  per  line  (80  or  132,  default  =  80). 

Ipi  is  the  number  of  lines  per  inch  (6  or  8,  default  =  6). 

P  causes  continuous  retries  when  the  printer  is  not  ready. 

Description 

This  form  of  the  MODE  command  configures  an  IBM  or  compatible  printer  connected  to 
parallel  port  «.  Its  effect  on  other  printer  types  may  vary.  The  command  has  the  side  effect 
of  canceling  any  redirection  that  was  previously  applied  to  the  specified  port  with  a 
Redirect  Printing  MODE  command. 

The  first  parameter,  LPTw,  designates  the  parallel  printer  port  to  be  configured  (LPTl, 
LPT2,  or  LPT3).  All  the  other  parameters  are  optional. 

The  cpl  parameter  selects  between  printing  80  characters  on  a  line  (the  default)  and  132 
characters  on  a  line.  The  Ipi  parameter  selects  between  6  lines  per  inch  (the  default)  and  8 
lines  per  inch.  (Note  that  the  attached  printer  must  be  capable  of  printing  132  characters 
per  line  or  8  lines  per  inch  and  of  understanding  IBM-compatible  printer-control  codes; 
otherwise,  specifying  these  values  will  have  no  effect.) 

The  last  parameter  in  the  command  line,  P,  configures  the  system  to  retry  output  contin¬ 
uously  (or  until  Ctrl-Break  is  pressed)  if  the  printer  is  not  ready  or  not  on  line  (interpreted 
by  the  computer  as  a  time-out  error),  rather  than  display  an  error  message.  (Note  that  if  P  is 
used  and  Ipi  is  omitted,  the  comma  preceding  Ipi  must  be  specified.)  Use  of  the  P  option 
causes  part  of  the  MODE  program  to  become  permanently  resident  in  memory.  (This 
option  is  not  available  in  PC-DOS  version  1.0.) 

Examples 

To  configure  the  printer  on  the  first  parallel  port  to  print  132  characters  per  line,  with  8 
lines  per  inch,  type 

OMODE  LPT  1:132,8  <Enter> 
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To  configure  the  system  to  continually  send  output  to  the  printer  on  the  second  parallel 
port  if  a  time-out  error  occurs  but  to  leave  the  other  values  at  their  defaults,  type 

OMODE  LPT2:,,P  <Enter> 

Messages 

DOS  2.0  or  later  required 

MODE  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Incorrect  DOS  version 

The  version  of  MODE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Infinite  retry  of  parallel  printer  timeout 

The  P  option  was  included  in  the  command  line  and  the  system  will  continuously  retry  to 
send  output  to  the  printer  attached  to  the  specified  port  if  it  is  not  ready  or  not  on  line. 

INTERNAL  ERROR  in  MODE  appUcation 

An  internal  error  occurred  in  the  MODE  utility  and  the  requested  reconfiguration  was  not 
carried  out. 

Invalid  parameters 

The  command  line  included  an  incorrect  parallel-port  specification  or  one  of  the  con¬ 
figuration  parameters  was  not  correct. 

LPTif:setfor  80 

The  specified  printer  has  been  configured  for  80  characters  per  line. 

LPT#i:setforl32 

The  specified  printer  has  been  configured  for  132  characters  per  line. 

Printer  error 

The  configuration  command  could  not  be  carried  out  because  the  printer  is  turned  off,  not 
ready,  or  not  on  line. 

Printer  lines  per  inch  set 

The  printer  has  successfully  been  configured  for  the  specified  6  or  8  lines  per  inch. 

Resident  portion  of  MODE  loaded 

The  P  option  was  specified  in  the  command  line  and  part  of  the  MODE  command  has 
become  permanently  resident  in  memory,  decreasing  slightly  the  amount  of  memory  avail¬ 
able  to  other  programs. 
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Set  Display  Mode 

Purpose 

Selects  the  active  video  adapter  and  its  display  mode  or  reconfigures  the  current  display. 
This  form  of  the  MODE  command  is  included  with  PC-DOS  beginning  with  version  2.0. 

Syntax 

MODE  display 
or 

MODE  [display\shift[,i:] 
where: 

display  is  a  video  adapter  and  display  mode  from  the  following  list: 

40  Color/graphics  adapter,  40  characters  per  line 

80  Color/graphics  adapter,  80  characters  per  line 

BW40  Color/graphics  adapter,  40  characters  per  line,  color  disabled  from 

composite  output 

BW80  Color/graphics  adapter,  80  characters  per  line,  color  disabled  from 
composite  output 

CO40  Color/graphics  adapter,  40  characters  per  line,  color  enabled 

CO80  Color/graphics  adapter,  80  characters  per  line,  color  enabled 

MONO  Monochrome  adapter 

shift  is  R  or  L,  to  shift  the  display  left  or  right  one  (40-column  display)  or  two 

(80-column  display)  character  positions. 

T  causes  a  test  pattern  to  be  displayed  for  screen  alignment. 

Description 

This  form  of  the  MODE  command  has  two  uses.  The  first  is  to  select  the  active  video 
adapter  and  its  display  mode  (if  more  than  one  adapter  is  present  in  the  system)  or  to 
reconfigure  the  current  adapter.  The  second  is  to  shift  the  screen  display  to  the  left  or  right 
to  center  it.  In  both  cases,  the  screen  is  cleared  as  a  side  effect  of  the  command. 

The  display  parameter  selects  the  active  video  adapter  and  mode  or  reconfigures  the  cur¬ 
rent  adapter.  If  a  display  adapter  that  is  not  available  is  specified,  MODE  displays  an  error 
message. 

The  shift  parameter  is  simply  the  single  character  R  or  L  preceded  by  a  comma.  Each  shift 
command  causes  the  screen  image  to  be  shifted  by  two  characters  if  the  display  adapter  is 
in  80-column  mode  or  by  one  character  if  it  is  in  40-column  mode.  When  the  T  option  is 


3.2 

External 
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also  included  in  the  command  line,  the  screen  image  is  shifted,  a  test  pattern  is  displayed, 
and  the  user  is  prompted  to  indicate  whether  the  screen  should  be  shifted  again.  Note  that 
use  of  shift  causes  part  of  the  MODE  program  to  become  permanently  resident  in  memory. 

Examples 

In  a  system  with  both  a  color/graphics  adapter  and  a  monochrome  display  adapter,  to 
select  the  monochrome  display  as  the  active  display,  type 

C>mODE  mono  <Enter> 

To  select  a  color  80-column  text  mode  on  the  color/graphics  adapter,  shift  the  screen  image 
two  characters  to  the  left,  and  display  a  test  pattern,  type 

OmODE  C080,L,T  <Enter> 

Messages 

DOS  2.0  or  later  required 

MODE  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Do  you  see  the  leftmost  0?  (Y/N) 

or 

Do  you  see  the  rightmost  9?  (Y/N) 

When  the  shift  and  T  options  are  used  together,  this  message  allows  the  user  to  shift  the 
test-pattern  display  successive  positions  until  it  is  properly  centered. 

Incorrect  DOS  version 

The  version  of  MODE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

INTERNAL  ERROR  in  MODE  appUcation 

An  internal  error  occurred  in  the  MODE  utility  and  the  requested  reconfiguration  was  not 
carried  out. 

Invalid  parameter 

The  specified  display  adapter  or  mode  is  not  available. 

Requested  Screen  Shift  out  of  range 

The  display  cannot  be  shifted  any  further. 

Unable  to  shift  Screen  left 

The  screen  has  already  been  shifted  as  far  left  as  possible  or  the  active  display  adapter  can¬ 
not  be  shifted  (monochrome  or  enhanced  graphics  adapter). 

Unable  to  shift  Screen  right 

The  screen  has  already  been  shifted  as  far  right  as  possible  or  the  active  display  adapter 
cannot  be  shifted  (monochrome  or  enhanced  graphics  adapter). 
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Configure  Serial  Port 

Purpose 

Controls  the  configuration  of  the  serial  communications  adapter.  This  form  of  the  MODE 
command  is  included  with  PC-DOS  b^inning  with  version  1.1. 

Syntax 

MODECOMn\:\baiid[,parity[,databit^,stopbits[,?]]]] 

where: 

COM«  is  the  serial  port  (n  =  1  or  2). 

baud  is  the  baud  rate  (1 10, 150, 300, 1200, 2400, 4800,  or  9600). 

parity  is  the  type  of  parity  checking  (N  =  none,  O  =  odd,  E  =  even,  default  =  E). 

databits  is  the  number  of  bits  per  character  (7  or  8,  default  =  7). 
stopbits  is  the  number  of  stop  bits  (1  or  2,  default  =  1 ,  except  with  110  baud  where 

default  =  2). 

P  causes  continuous  retries  when  the  output  device  is  not  ready. 

Description 

This  form  of  the  MODE  command  configures  the  specified  serial  port  for  communication 
with  an  external  device  such  as  a  printer,  a  terminal,  or  a  modem. 

The  first  parameter,  COMn,  designates  the  serial  port  to  be  configured  (COMl  or  COM2). 
Except  for  the  port  number  and  the  baud  rate,  which  are  required,  a  parameter  can  be  left 
unchanged  by  entering  a  comma  without  a  value  in  its  position  in  the  command  line.  (If 
all  optional  parameters  are  to  be  left  unchanged  and  P  is  not  used  in  the  command  line, 
no  commas  are  required.) 

The  baud  rate  must  be  one  of  the  values  110, 150, 300, 600, 1200,  2400, 4800,  or  9600.  The 
first  two  digits  can  be  used  as  an  abbreviation  for  the  full  value. 

The  parity  parameter  specifies  the  type  of  parity  checking  to  be  done  on  each  character 
and  must  be  one  of  the  characters  N,  O,  or  E  (for  none,  odd,  or  even,  respectively);  the 
default  is  even  parity.  The  databits  parameter  specifies  the  length  of  a  character  and  must 
be  either  7  or  8;  the  default  is  7.  The  stopbits  parameter  is  either  1  or  2.  If  baud  is  set  for 
110,  the  default  number  of  stopbits  is  2;  otherwise,  the  default  is  1. 

The  last  parameter  in  the  command  line,  P,  configures  the  system  to  retry  output  con¬ 
tinuously  (or  until  Ctrl-Break  is  pressed)  if  the  device  interfaced  to  the  serial  port  is  not 
ready  or  not  on  line,  rather  than  display  an  error  message.  Use  of  the  P  option  causes  part 
of  the  MODE  program  to  become  permanently  resident  in  memory. 
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Consult  the  user’s  manual  for  the  specific  printer,  modem,  terminal,  or  other  device  to  de¬ 
termine  the  proper  settings  for  the  MODE  parameters. 

If  a  serial  printer  is  to  be  used  instead  of  LPTl  as  the  system’s  default  printer,  the  Redirect 
Printing  MODE  command  must  be  specified  after  the  Configure  Serial  Port  MODE 
command. 

Example 

To  configure  the  first  serial  port  for  9600  baud,  no  parity,  8  databits,  and  1  stop  bit,  type 

OMODE  COM1  :  9600,N,  8, 1  <Enter> 

Messages 

COMif ;  haudy  parity y  datahitSy  stopbitSy  timeout 

After  the  serial  port  is  configured  successfully,  MODE  displays  an  advisory  message  con¬ 
firming  the  settings.  If  the  P  option  was  not  used  in  the  command  line,  a  hyphen  character 
(-)  is  displayed  for  timeout,  to  indicate  no  continuous  retries  if  the  printer  is  not  ready  or  is 
not  on  line. 

COM  port  does  not  exist 

The  serial  port  specified  in  the  command  line  does  not  exist  in  the  system. 

DOS  2.0  or  later  required 

MODE  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Incorrect  DOS  version 

The  version  of  MODE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

INTERNAL  ERROR  in  MODE  appUcation 

An  internal  error  occurred  in  the  MODE  utility  and  the  requested  reconfiguration  was  not 
carried  out. 

Invalid  baud  rate  specified 

The  baud  rate  included  in  the  command  line  was  not  one  of  the  allowed  values  or  was  ab¬ 
breviated  incorrectly. 

Invalid  parameters 

The  command  line  specified  a  COM  port  that  does  not  exist  in  the  system  or  one  of  the 
configuration  parameters  for  the  COM  port  was  not  valid. 

No  COM:  ports 

The  computer  does  not  have  any  serial  ports  installed. 

Resident  portion  of  MODE  loaded 

The  P  option  was  specified  in  the  command  line  and  part  of  the  MODE  command  has 
become  permanently  resident  in  memory,  decreasing  slightly  the  amount  of  memory  avail¬ 
able  to  other  programs. 
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MODE  3.2 

Redirect  Printing  External 

Purpose 

Redirects  output  from  a  parallel  port  to  a  serial  communications  port.  This  form  of  the 
MODE  command  is  included  with  PC-DOS  beginning  with  version  1.1. 

Syntax 

MODE  LPTn[:][=COMw[:]] 
where: 

LPTw  is  the  parallel  port  to  be  redirected  in  =  1,  2,  or  3). 

COMn  is  the  serial  port  (n  =  1  or  2)  to  be  used  for  output  instead  of  LPT n. 

Description 

This  form  of  the  MODE  command  redirects  any  output  for  the  specified  parallel  port, 
sending  it  to  the  specified  serial  communications  port  instead.  The  parallel  port  can  be 
LPTl,  LPT2,  or  LPT3;  the  serial  port  can  be  either  COMl  or  COM2.  A  Configure  Serial  Port 
MODE  command  is  required  before  the  Redirect  Printing  MODE  command,  to  configure 
the  serial  port  for  the  proper  baud  rate,  parity,  word  length,  and  stop  bits. 

Redirection  can  be  canceled  by  entering  MODELPTn  alone. 

Use  of  MODE  to  redirect  printer  output  causes  part  of  the  MODE  program  to  become 
permanently  resident  in  memory.  Canceling  the  redirection  will  not  remove  this  resident 
portion  from  memory. 

Example 

To  cause  all  output  to  the  first  parallel  port  (LPTl)  to  be  redirected  to  the  first  serial  port 
(COMl),  type 

C>MODE  LPTl :=C0M1 :  <Enter> 

Messages 

DOS  2.0  or  later  required 

MODE  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Illegal  device  name 

Either  the  parallel  port  or  the  serial  port  specified  in  the  command  line  does  not  exist  in 
the  system. 
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Incorrect  DOS  version 

The  version  of  MODE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

INTERNAL  ERROR  in  MODE  application 

An  internal  error  occurred  in  the  MODE  utility  and  the  requested  reconfiguration  was  not 
carried  out. 

LPTii:  not  redirected 

No  serial  port  was  specified  and  any  previous  redirection  from  the  specified  parallel  port 
was  canceled. 

LPTii:  redirected  to  COMii: 

The  MODE  command  has  successfully  redirected  the  output  for  the  specified  parallel  port 
to  the  specified  serial  port. 

Resident  portion  of  MODE  loaded 

Part  of  the  MODE  command  has  become  permanently  resident  in  memory,  decreasing 
slightly  the  amount  of  memory  available  to  other  programs. 
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MORE  2.0  and  later 

Display  by  Screenful  External 


Purpose 

Displays  output  one  screenful  at  a  time  on  standard  output. 

Syntax 

MORE 

Description 

The  MORE  filter  reads  lines  of  text  from  standard  input  and  sends  them  to  standard  output 
one  screenful  (23  lines)  at  a  time.  At  the  end  of  each  screenful,  MORE  displays  the  message 
—  More—  and  then  waits  for  any  key  to  be  pressed  before  it  continues.  (Pressing  Crtl-C  or 
Ctrl-Break  terminates  the  MORE  filter.) 

The  default  input  device  is  the  keyboard;  the  default  output  device  is  the  video  display. 
Because  standard  input  can  be  redirected,  the  MORE  filter  can  also  accept  input  from 
another  character  device  or  a  file  or  from  the  piped  output  of  another  program  or  filter. 
Similarly,  the  output  of  MORE  can  be  redirected  to  any  character  device  or  file  or  can  be 
piped  to  another  program  (however,  the  message  —  More  -  will  be  included  with  the 
redirected  or  piped  output). 

Examples 

To  display  the  file  SHELL.C  one  screenful  at  a  time,  type 

C>MORE  <  SHELL.C  <Enter> 

To  display  the  directory  of  \MASM\ SOURCE  in  the  current  drive  one  screenful  at  a  time, 
pipe  the  output  of  the  DIR  command  to  the  MORE  filter  by  typing 

ODIR  \MASM\SOURCE  1  MORE  <Enter> 

Messages 

—  More  — 

This  informational  message  is  displayed  at  the  end  of  each  screenful  of  text.  Press  any  key 
to  resume  output. 

MORE:  Incorrect  DOS  version 

The  version  of  MORE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 
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PATH  2.0  and  later 

Define  Command  Search  Path  Internal 


Purpose 

Specifies  one  or  more  additional  drives  and/or  directories  to  be  searched  for  a  program  or 
batch  file  if  the  file  cannot  be  found  in  the  current  or  specified  drive  and  directory. 

Syntax 

PATH  [driveMpath]  [;  [drive{\[path] . . .  ] 
or 

PATH; 

where: 

drive  is  the  drive  containing  the  disk  to  be  searched  for  the  executable  file. 

path  is  the  name  of  the  directory  to  be  searched  for  the  executable  file. 

Description 

when  a  command  line  is  entered  at  the  MS-DOS  system  prompt,  the  command  processor 
first  checks  to  see  if  the  specified  command  is  one  of  its  internal  commands.  If  it  is  not, 
the  command  processor  searches  the  current  directory  of  the  current  drive  for  a  file  with 
the  same  name  and  the  extension  .COM,  .EXE,  or  .BAT,  in  that  order.  If  found,  the  file  is 
loaded  into  memory  and  executed  (if  the  extension  is  .COM  or  .EXE)  or  interpreted  by  the 
resident  batch-file  processor  (if  the  extension  is  .BAT);  otherwise,  MS-DOS  displays  the 
message  Bad  command  or  file  name,  followed  by  the  system  prompt.  In  versions  3.0  and 
later,  a  path  can  precede  the  command  name,  causing  MS-DOS  to  make  the  initial  search 
for  a  program  or  batch  file  under  the  specified  path. 

The  PATH  command  designates  one  or  more  disk  drives  and/or  directory  paths  to  be 
searched  sequentially  for  a  program  or  batch  file  if  the  file  cannot  be  found  in  the  current 
or  specified  drive  and  directory.  The  drives  and/or  directory  paths  are  searched  in  the 
order  they  appear  in  the  PATH  command.  Multiple  drive.path  pairs  can  be  specified, 
separated  by  semicolons.  A  copy  of  the  PATH  string  is  passed  to  each  executing  process  as 
a  part  of  the  process’s  environment. 

If  the  drive  parameter  is  specified  without  an  associated  path,  MS-DOS  assumes  the  root 
directory  of  drive.  If  the  PATH  command  is  followed  only  by  a  semicolon,  MS-DOS  deletes 
the  existing  path.  If  the  PATH  command  is  entered  with  no  parameters,  MS-DOS  displays 
the  existing  path. 

Invalid  or  nonexistent  drives  and/or  paths  in  the  PATH  command  do  not  result  in  an  error 
message  but  are  ignored  when  the  PATH  string  is  inspected  later  during  a  search  for  a  pro¬ 
gram  or  batch  file. 
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The  PATH  command  is  generally  placed  in  the  AUTOEXEC.BAT  file  on  the  system  disk  so 
that  the  search  order  will  be  defined  each  time  the  system  is  turned  on  or  restarted. 

Examples 

To  define  the  directory  \BIN  on  the  disk  in  drive  A  as  the  directory  to  be  searched  for  a 
program  or  batch  file  if  the  file  is  not  found  in  the  current  or  specified  directory,  type 

OPATH  A:\BIN  <Enter> 

Subsequent  entry  of  the  command 

OPATH  <Enter> 

results  in  the  display 

PATH=A:\BIN 

To  define  the  root,  \BIN,  \DOS,  and  \DATA  directories  on  drive  C  and  the  \UTIL  directory 
on  the  disk  in  drive  B  as  the  locations  to  be  searched  for  a  program  or  batch  file  if  the  file 
is  not  found  in  the  current  or  specified  directory,  type 

OPATH  C:\; C:\BIN; C:\DOS; C:\DATA; B:\UTIL  <Enter> 

To  delete  the  current  search  path,  type 

OPATH  ;  <Enter> 

Message 

No  Path 

The  PATH  command  was  entered  without  parameters  and  no  search  path  is  currently  in 
effect. 
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PRINT  2.0  and  later 

Print  Spooler  External 


Purpose 

Loads  and  configures  the  background  print  spooler  or  adds  or  deletes  files  from  the  print 
spooler’s  queue. 

Syntax 

PRINT  [/Ti'.device]  [/B:«]  [/M:w]  [/Q: w]  [/S:w]  [/U: w]  [[drive‘][path]filenaine]  [/C][/P] 
[[[drive{\[path\filename]  [/C][/P] . . .] 


or 

PRINT /T 

where: 

filename 

/B:n 

/C 

/D:  device 

/M:n 

/P 

/Q:n 

/S:n 

/T 

/U:« 


is  the  name  of  the  file  to  be  added  to  or  deleted  from  the  print  queue, 
optionally  preceded  by  a  drive  (and  a  path  with  versions  3.0  and  later); 
wildcard  characters  are  permitted. 

sets  the  print-buffer  size  in  bytes  (1-32767,  default  =  512)  (versions  3  0 
and  later). 

deletes  the  immediately  preceding  file  and  all  subsequent  files  from  the 
print  queue  (until  a  /P  switch  is  encountered). 

is  the  character  device  to  be  used  for  printing  (default  =  PRN);  must  be  the 
first  switch,  if  used  (versions  3.0  and  later). 

is  the  length  of  time  in  timer  ticks  that  PRINT  keeps  control  during  each 
of  its  time  slices  (1-255,  default  =  2)  (versions  3.0  and  later), 
adds  the  immediately  preceding  file  and  all  subsequent  files  to  the  print 
queue  (until  a  /C  switch  is  encountered). 

is  the  maximum  number  of  files  allowed  in  the  print  queue  (1-32,  default 
=  10)  (versions  3.0  and  later). 

is  the  number  of  time  slices  per  second  that  PRINT  gives  control  to  the 
foreground  process  (1-255,  default  =  8)  (versions  3.0  and  later), 
terminates  printing  and  empties  the  print  queue, 
is  the  number  of  timer  ticks  that  PRINT  waits  for  a  busy  or  unavailable 
printer  or  for  a  disk  access  or  MS-DOS  function  call  to  terminate  before 
giving  up  the  time  slice  (1-255,  default  =  1)  (versions  3.0  and  later). 
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Description 

The  PRINT  utility  is  a  terminate-and-stay-resident  (TSR)  program  that  can  print  files  from 
disk  while  other  programs  are  running.  PRINT  maintains  a  first-in,  first-out  (FIFO)  queue 
that  can  hold  the  names  of  as  many  as  32  files.  PRINT  does  not  attempt  to  interpret  the 
contents  of  a  file,  except  to  expand  tab  characters  (ASCII  code  09H)  with  spaces  to  the 
next  eight-column  boundary  and  to  interpret  1  AH  characters  as  end-of-file  marks.  (A  pro¬ 
gram  such  as  PRINT  that  can  transfer  files  to  a  printer  without  any  special  knowledge  of 
their  contents  or  origin  is  called  a  print  spooler.) 

Note:  The  PRINT  utility  continues  printing  a  file  until  it  encounters  an  end-of-file  charac¬ 
ter  (1  AH).  Therefore,  if  PRINT  is  used  with  nontext  files,  it  may  encounter  a  1  AH  character 
before  reaching  the  end  of  the  file  and  terminate  printing  before  the  entire  file  has  been 
processed.  In  such  cases,  files  should  be  printed  using  the  COPY  command,  with  PRN  as 
the  destination. 

The  PRINT  program  employs  a  technique  called  time-slicing,  which  is  based  on  its  use  of 
the  timer-tick  interrupt  and  its  detailed  knowledge  of  MS-DOS.  PRINT  uses  this  interrupt, 
which  occurs  18.2  times  per  second  on  IBM  PC-compatible  machines,  to  divide  the  pro¬ 
cessor’s  time  between  an  application  or  utility  program  (such  as  a  word  processor  or  a 
spreadsheet)  and  the  print  spooler.  Because  the  application  program  typically  controls  the 
display  screen  and  the  keyboard  and  receives  most  of  the  CPU  time,  it  is  called  the  fore¬ 
ground  program.  The  print  spooler,  which  receives  a  lesser  part  of  the  CPU  time  and 
usually  operates  without  indicating  its  status  or  progress  to  the  operator,  is  called  the  back¬ 
ground  program. 

The  /B: «,  /D:  device,  /Q:  n,  /M:  n,  /S:  w,  and  /U:  n  switches  configure  the  PRINT  utility. 
These  switches  are  used  only  the  first  time  the  PRINT  command  is  entered  after  the  sys¬ 
tem  has  been  turned  on  or  restarted. 

The  /T>\device  switch,  which  must  be  the  first  switch  in  the  command  line  if  used,  speci¬ 
fies  the  peripheral  device  the  print  spooler  is  to  use  for  output.  This  can  be  any  legal 
character-output  device  that  is  present  in  the  system.  If  /T>\device  is  not  included  in  the 
first  PRINT  command,  PRINT  prompts  the  user  to  select  an  output  device  (default  =  PRN). 
Once  an  output  device  has  been  assigned,  a  new  device  cannot  be  selected  without  restart¬ 
ing  the  system. 

The  /B:  n  switch  sets  the  size  of  PRINT’S  file  buffer,  which  controls  the  amount  of  data  that 
is  read  from  a  file  at  one  time  for  printing.  The  value  of  n  must  be  between  1  and  32767 
bytes  (default  value  =  512).  Large  file  buffers  reduce  the  amount  of  extra  disk  activity 
caused  by  the  print  spooler,  but  they  also  reduce  the  amount  of  memory  available  for  use 
by  other  programs.  The  /Q:  w  switch  controls  the  size  of  PRINT’S  queue — that  is,  the 
number  of  files  that  can  be  held  in  the  buffer  pending  printing.  The  queue  can  be  con¬ 
figured  to  hold  1  to  32  files  (default  =  10). 

The  /S:  n,  /M: «,  and  /U:  n  switches,  available  only  with  versions  3.0  and  later,  control  the 
time-slicing  behavior  of  PRINT.  The  /S:  n  switch  sets  the  number  of  time  slices  per 
second — that  is,  how  many  times  per  second — PRINT  will  be  given  control;  n  is  in  the 
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range  1  through  255  (default  =  8).  The  /M:  n  switch  sets  the  length  of  time  (in  timer  ticks) 
that  PRINT  will  keep  control  during  each  of  its  time  slices;  n  is  in  the  range  1  through  255 
(default  =  2).  The  /U:  n  switch  specifies  how  long  (in  timer  ticks)  PRINT  should  wait  for  a 
busy  or  unavailable  printer  or  for  a  disk  access  or  MS-DOS  function  call  to  terminate  before 
giving  up  its  time  slice;  again,  n  is  in  the  range  1  through  255  (default  =  1).  Unless  there 
are  special  circumstances,  the  default  values  for  these  switches  will  give  acceptable 
performance. 

Files  are  added  to  the  print  queue  by  entering  PRINT  followed  by  one  or  more  pathnames. 
Files  are  printed  in  the  order  they  are  placed  in  the  queue.  At  the  end  of  each  file,  the  print 
spooler  advances  the  paper  to  the  top  of  the  next  page.  If  a  filename  containing  wildcards 
is  used,  all  matching  files  are  added  to  the  queue  in  the  order  in  which  they  appear  in  the 
directory.  After  a  file  is  queued  for  printing,  it  should  not  be  renamed  or  erased,  nor  should 
the  disk  containing  the  file  be  removed,  until  the  printing  is  complete. 

Note:  Each  print  queue  entry  can  be  a  maximum  of  63  characters,  including  the  drive  and 
path. 

The  /P  and  /C  switches  allow  files  to  be  added  to  and  deleted  from  the  print  queue  in  the 
same  command  line.  The  /P  switch  (the  default)  adds  to  the  print  queue  the  immediately 
preceding  file  in  the  command  line  and  all  subsequent  files  until  a  /C  switch  is  encoun¬ 
tered.  Conversely,  the  /C  switch  cancels  printing  for  the  immediately  preceding  file  in  the 
command  line  and  for  all  subsequent  files  until  a  /P  switch  is  encountered.  If  a  canceled 
file  is  currently  being  printed,  PRINT  prints  the  message  File  filename  canceled  by  opera¬ 
tor  on  the  listing,  sounds  the  printer's  alarm  (if  it  has  one),  and  advances  the  paper  to  the 
top  of  the  next  page. 

The  /T  switch  terminates  printing  by  deleting  all  files  from  the  print  queue.  If  a  file  is  cur¬ 
rently  being  printed,  PRINT  prints  the  message  All files  canceled  by  operator  on  the  list¬ 
ing,  sounds  the  printer’s  alarm  (if  it  has  one),  and  advances  the  paper  to  the  top  of  the  next 
page. 

If  PRINT  encounters  a  disk  error  while  attempting  to  print  a  particular  file,  it  cancels  that 
file,  prints  an  error  message  on  the  printer,  sounds  the  printer’s  alarm  (if  it  has  one),  ad¬ 
vances  the  paper  to  the  top  of  the  next  page,  and  goes  to  the  next  file  in  the  print  queue. 

If  the  PRINT  command  is  entered  with  no  parameters,  the  contents  of  the  print  queue  are 
displayed. 

Because  PRINT  is  a  TSR  utility,  it  reduces  the  amount  of  memory  available  for  use  by  other 
programs.  The  only  way  to  recover  the  memory  occupied  by  PRINT,  even  after  printing  is 
complete,  is  to  restart  the  system. 

Examples 

To  install  and  configure  the  PRINT  program  and  specify  the  auxiliary  device  (AUX)  as  the 
printing  device,  with  a  print  queue  that  can  hold  as  many  as  32  filenames  and  with  a  buffer 
size  of  2048  bytes,  type 

C>PRINT  /D:AUX  /Q:32  /B:2048  <Enter> 


Section  III:  User  Commands  901 


PRINT 


To  add  the  file  DOC.TXT  in  the  current  directory  of  the  current  drive  to  the  print  spooler’s 
queue,  type 

C>PRINT  DOC.TXT  <Enter> 

To  delete  the  file  READY.TXT  from  the  print  queue  and  simultaneously  add  the  files 
FINAL.TXT  and  REPORTTXT  to  the  queue,  type 

C>PRINT  READY.TXT  /C  FINAL.TXT  /P  REPORT.TXT  <Enter> 

To  cancel  the  file  being  printed  and  remove  all  pending  files  from  the  print  queue,  type 

C>PRINT  /T  <Enter> 

Messages 

filename  File  not  found 

A  disk  was  changed  or  the  file  was  renamed  or  erased  after  the  PRINT  command  was  en¬ 
tered  but  before  the  file  was  actually  printed. 

filename  File  not  in  print  queue 

A  command  line  with  a  /C  switch  specified  a  file  that  is  not  in  the  print  queue. 

filename  is  currently  being  printed 

This  informational  message  shows  which  file  PRINT  is  currently  printing. 

filename  is  in  queue 

This  informational  message  shows  which  file  is  in  the  queue  waiting  to  be  printed. 

filename  Pathname  too  long 

The  pathname  of  a  file  to  be  printed  exceeded  63  characters. 

Access  denied 

An  attempt  was  made  to  print  a  locked  file. 

All  files  canceled  by  operator 

The  /T  switch  was  included  in  the  command  line.  PRINT  terminates  printing  of  the  cur¬ 
rent  file,  empties  the  print  queue,  sounds  the  printer  alarm  (if  it  has  one),  and  advances  the 
paper  to  the  top  of  the  next  page. 

Cannot  use  PRINT  -  Use  NET  PRINT 

If  network  support  has  been  installed,  the  NET  PRINT  command  must  be  used  to  print 
files. 

Errors  on  list  device  indicate  that  it 
may  be  off-line.  Please  check  it. 

The  printer  has  been  turned  off  or  placed  off  line  while  files  are  still  in  the  print  queue. 

File  filename  canceled  by  operator 

A  PRINT  command  was  entered  with  the  /C  switch  to  cancel  a  specific  file.  If  the  specified 
file  is  currently  being  printed,  PRINT  terminates  printing  of  the  file,  sounds  the  printer 
alarm  (if  it  has  one),  advances  the  paper  to  the  top  of  the  next  page,  and  resumes  printing 
with  the  next  file  in  the  queue. 
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Incorrect  DOS  version 

The  version  of  PRINT  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Invalid  drive  specification 

A  drive  letter  specified  in  the  command  line  is  invalid  or  does  not  exist  in  the  system. 

Invalid  parameter 

The  command  line  included  an  invalid  switch  or  configuration  switches  were  used  after 
the  first  time  the  PRINT  command  was  used. 

List  output  is  not  assigned  to  a  device 

An  invalid  destination  device  was  previously  entered.  Restart  the  system  and  specify  a 
valid  device  in  the  PRINT  command. 

Name  of  list  device  [PRN]: 

This  message  is  displayed  in  response  to  the  first  PRINT  command  line  if  the  /T>\device 
switch  was  not  included.  Specify  any  valid  character-output  device  (default  =  PRN). 

No  paper  error  writing  device  device 

An  out-of-paper  device  error  was  detected  while  printing  on  the  specified  device. 

PRINT  queue  is  empty 

No  files  are  waiting  to  be  printed. 

PRINT  queue  is  full 

No  additional  files  can  be  added  to  the  print  queue  until  the  current  file  is  printed.  To  in¬ 
crease  the  size  of  the  print  queue,  restart  the  system  and  use  the  /Q:  n  switch  in  the  PRINT 
command. 

Resident  part  of  PRINT  installed 

This  informational  message  is  displayed  on  the  first  entry  of  a  PRINT  command  to  indicate 
that  the  PRINT  utility  is  now  resident  in  memory.  The  amount  of  memory  available  to  ap¬ 
plication  programs  is  reduced  accordingly. 
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PROMPT  2.0  and  later 

Define  System  Prompt  Internal 


Purpose 

Defines  the  form  of  the  command  processor’s  prompt.  This  command  is  included  in 
PC-DOS  beginning  with  version  2.1. 

Syntax 

PROMPT  [string] 
where: 

string  is  a  combination  of  ordinary  printable  characters  and  the  following  special  dis¬ 

play  codes: 


Code 


$b 

$d 

$e 

$g 

$h 

$1 

$n 

$p 

$q 

$t 

$v 

$_ 

$$ 


Meaning 

I  character 

Current  date  (in  the  form  Day  mm-dd-yyyjd 
Escape  character  (IBH) 

>  character 

Backspace  character  (erases  the  previous  character) 
<  character 
Current  drive 
Current  drive  and  path 
=  character 

Current  time  (in  the  form  hh\mm\ss.hK) 

MS-DOS  version  number 

Carriage  return/linefeed  pair  (starts  a  new  line) 

$  character 


Description 


The  system’s  default  command  processor,  COMMAND.COM,  displays  a  prompt  on  the 
screen  whenever  it  is  ready  to  accept  a  command  from  the  user.  The  command  processor 
determines  the  format  of  the  prompt  from  the  PROMPT  environment  variable,  if  it  exists. 
Otherwise,  it  uses  the  default  format,  which  in  most  OEM  implementations  of  MS-DOS  is 
the  letter  of  the  current  drive  followed  by  a  greater-than  sign  (for  example,  C>). 


The  PROMPT  command  allows  the  user  to  customize  the  system  prompt.  This  command 
is  usually  included  in  the  AUTOEXEC.BAT  file  so  that  MS-DOS  displays  the  custom  prompt 
when  the  system  is  turned  on  or  restarted. 
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The  string  parameter  can  be  any  combination  of  printable  characters  and  the  special  $ 
control  codes  listed  in  the  preceding  table.  The  special  $  codes  allow  certain  variable  in¬ 
formation,  such  as  the  date  and  time,  to  be  obtained  from  the  operating  system  and  dis¬ 
played  as  part  of  the  prompt.  Such  system  information  can  be  edited  in  the  prompt  with 
the  backspace  function,  which  is  invoked  with  the  code  $h. 

Note:  When  the  time  is  displayed  as  part  of  a  prompt,  it  is  updated  only  when  the  com¬ 
mand  processor  redisplays  the  prompt. 

The  escape  character,  invoked  with  the  code  $e,  can  be  used  to  include  standard  ANSI 
escape  sequences  in  string  to  control  the  appearance  of  text  or  its  position  on  the  screen. 
See  USER  COMMANDS:  ansi.sys  for  further  information  on  the  ANSI  escape  sequences 
and  the  ANSI  device  driver. 

If  PROMPT  is  entered  with  no  parameters,  the  system  prompt  is  reset  to  the  default  format. 

The  PROMPT  command  works  by  modifying  the  PROMPT  environment  variable.  The 
same  result  can  be  obtained  using  the  SET  command  with  PROMPT=stnng  as  its  argu¬ 
ment.  See  USER  COMMANDS:  set  for  further  discussion  of  the  environment  block  and 
environment  variables. 

Examples 

To  define  the  system  prompt  as  the  word  Command  followed  by  a  colon,  type 

C>PROMPT  Command:  <Enter> 

On  fixed-disk-based  systems  it  is  desirable  to  display  the  current  drive  and  path  as  part  of 
the  prompt.  To  define  such  a  prompt  followed  by  a  >  character,  type 

OPROMPT  $p$g  <Enter> 

To  define  the  system  prompt  to  display  the  time,  date,  and  current  drive  and  path  followed 
by  a  >  character,  each  on  a  separate  line,  type 

OPROMPT  $t$_$d$_$p$g  <Enter> 

The  system  will  respond  with  a  display  in  the  following  form: 

16:07:31 .56 
Thu  6-18-1987 
C:\BIN\DOS> 

To  create  a  prompt  that  displays  the  time  without  the  seconds  and  hundredths  of  a  second, 
followed  by  a  space  and  the  date  without  the  year,  followed  by  a  space  and  the  current 
drive  and  a  >  character,  type 

C>PROMPT  $t$h$h$h$h$h$h  $d$h$h$h$h$h  $n$g  <Enter> 

The  system  will  respond  with 

16:07  Thu  6-18  C> 
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To  define  a  prompt  that  always  displays  the  current  time  and  date  in  the  upper  right  corner 
of  the  screen  before  displaying  the  current  drive  and  the  >  character  on  the  current  line, 
type 

C>PROMPT  $e[s$e[0;60H$t$h$h$h$h$h$h  $d$e[u$n$g  <Enter> 

The  escape  sequence  $e[s  saves  the  current  cursor  position;  the  sequence  $e[0;60H  posi¬ 
tions  the  cursor  at  row  0,  column  60;  the  next  several  codes  format  the  date  and  time;  the 
sequence  $e[u  restores  the  original  cursor  position.  (This  example  requires  that  the  ANSI 
driver  be  loaded  to  interpret  the  escape  sequences.) 
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RAMDRIVE.SYS 

Virtual  Disk 

Purpose 

Creates  a  virtual  disk  in  memory. 

Syntax 

DEVlCE=[drive’][path]RAMDRlVE,SYS  [size]  [sector]  [directory]  [Al/E] 
where: 

size  is  the  size  of  the  virtual  disk  in  kilobytes  (minimum  =  l6,  default  =  64). 

sector  is  the  sector  size  in  bytes  (128,  256,  512,  or  1024;  default  =  128). 

directory  is  the  maximum  number  of  entries  in  the  virtual  disk’s  root  directory 

(3-1024,  default  =  64). 

A  causes  RAMDRI VE  to  use  Lotus/Intel/Microsoft  Expanded  Memory  for 

storage  (cannot  be  used  with  /E). 

/E  causes  RAMDRI  VE  to  use  extended  memory  for  storage  (cannot  be  used 

with  A). 

Note:  Unless  a  A  or  /E  switch  is  used,  the  virtual  disk  is  created  in  conventional  memory. 

Description 

The  RAMDRIVE.SYS  installable  device  driver  allows  the  configuration  of  one  or  more 
virtual  disks  (sometimes  referred  to  as  electronic  disks  or  R AMdisks).  A  virtual  disk  is  im¬ 
plemented  by  mapping  a  disk’s  structure — directory,  file  allocation  table,  and  files  area — 
onto  an  area  of  random-access  memory,  rather  than  onto  actual  sectors  located  on  a 
magnetic  recording  medium.  Access  to  files  stored  on  a  virtual  disk  is  very  fast,  because 
no  moving  parts  are  involved  and  the  “disk”  operates  at  the  speed  of  the  system’s  memory. 

Warning:  Because  a  RAMdisk  resides  entirely  in  RAM  and  is  therefore  volatile,  any  infor¬ 
mation  stored  there  is  irretrievably  lost  when  the  computer  loses  power  or  is  restarted. 

RAMDRIVE.SYS  can  create  a  virtual  disk  in  conventional  memory,  extended  memory,  or 
Lotus/Intel/Microsoft  Expanded  Memory.  Conventional  memory  is  the  term  for  the  up- 
to-640  KB  of  RAM  that  contain  MS-DOS  and  any  application  programs.  Extended  memory 
is  the  term  for  the  memory  at  addresses  above  1  MB  (lOOOOOH)  that  is  available  on  80286- 
based  personal  computers  such  as  the  IBM  PCAT.  Expanded  memory  is  the  term  for  a  sub¬ 
system  of  bank-switched  memory  boards  (and  a  driver  to  manage  them)  that  is  compatible 
with  the  Lotus/Intel/Microsoft  Expanded  Memory  Specification  (LIM  EMS). 

A  virtual  disk  can  be  installed  in  conventional  memory  by  simply  inserting  the  line 
DEVICE=RAMDRIVE.SYS  into  the  system’s  CONFIG.SYS  file  and  restarting  the  system.  A 


3.2 

External 
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new  “drive”  then  becomes  available  in  the  system,  with  a  default  size  of  64  KB,  128-byte 
sectors,  and  64  available  directory  entries  (assuming  memory  is  sufficient).  The  virtual  disk 
is  assigned  the  next  available  drive  letter  (which  is  displayed  in  RAMDRI  VE’s  sign-on  mes¬ 
sage).  The  drive  letter  assigned  depends  on  the  number  of  other  physical  and  virtual  disks 
in  the  system  and  also  on  the  position  of  the  DEVICE=RAMDRIVE.SYS  line  in  the  CON¬ 
FIG.SYS  file  relative  to  other  installed  block  devices.  Available  memory  permitting,  multi¬ 
ple  virtual  disks  can  be  created  by  using  multiple  DEVICE=RAMDR1VE.SYS  lines.  Several 
optional  parameters  allow  the  user  to  customize  the  size  and  configuration  of  the  virtual 
disk  and  to  use  extended  memory  or  expanded  memory  if  it  is  available. 

The  size  parameter  specifies  the  amount  of  RAM,  in  kilobytes,  to  be  allocated  to  the  virtual 
disk.  The  default  is  64  KB,  but  any  size  from  16  KB  to  the  total  amount  of  available  memory 
can  be  specified. 

The  sector  parameter  sets  the  virtual  sector  size  used  within  the  virtual  disk.  The  sector 
value  can  be  128,  256,  512,  or  1024  bytes  (default  =  128  bytes).  Selection  of  the  smallest  sec¬ 
tor  size  results  in  a  minimum  of  wasted  virtual  disk  space  per  file  but  also  results  in  a 
somewhat  slower  transfer  of  data.  Physical  disk  devices  on  IBM  PC-compatible  systems 
always  use  512-byte  sectors. 

Warning:  The  1024-byte  sector  size  is  not  supported  in  most  implementations  of  MS-DOS 
and  will  terminate  the  installation  of  RAMDRIVE.SYS  if  it  is  used.  Check  the  documenta¬ 
tion  included  with  the  computer  to  see  if  this  value  is  supported. 

The  directory  parameter  sets  the  number  of  available  entries  in  the  virtual  disk’s  root 
directory.  The  allowed  range  is  3  to  1024  (default  =  64).  Each  directory  entry  requires  32 
bytes.  RAMDRI VE  rounds  the  number  of  available  directory  entries  up,  if  necessary,  so 
that  an  integral  number  of  sectors  are  assigned  to  the  root  directory. 

The  /A  switch  causes  Lotus/Intel/Microsoft  Expanded  Memory  to  be  used  for  the  virtual 
disk,  rather  than  conventional  memory;  the  /E  switch  causes  extended  memory  to  be  used. 
Either  option  allows  very  large  virtual  disks  to  be  configured  while  still  leaving  the  max¬ 
imum  amount  of  conventional  memory  available  for  use  by  application  programs.  The  /A 
and  /E  switches  cannot  be  used  together. 

Note:  If  RAMDRI  VE  uses  conventional  memory  for  virtual  disk  storage,  the  memory  can¬ 
not  be  reclaimed  except  by  modifying  the  CONFIG.SYS  file  and  restarting  the  system. 

Examples 

To  create  a  virtual  disk  drive  with  the  default  values  of  64  KB  disk  size,  128-byte  sectors, 
and  64  available  directory  entries,  include  the  following  command 

DEVICE=RAMDRIVE . SYS 

in  the  CONFIG.SYS  file  and  restart  the  system. 
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To  create  a  4  MB  virtual  disk  drive  in  Lotus/Intel/Microsoft  Expanded  Memory,  with 
512-byte  sectors  and  224  available  directory  entries,  when  RAMDRIVE.SYS  is  located  in  a 
directory  named  \  DRIVERS  on  drive  C,  include  the  command 

DEVICE=C: \DRIVERS\RAMDRIVE.SYS  4096  512  224  /A 

in  the  CONFIG.SYS  file  and  restart  the  system. 

Messages 

Microsoft  RAMDrive  version  n.nn  virtual  diskX: 

Disk  size:  nnk 
Sector  size:  nnn  bytes 
Allocation  unit:  n  sectors 
Directory  entries:  nnn 

RAMDRIVE.SYS  was  successfully  installed  and  this  message  informs  the  user  of  the  ver¬ 
sion  of  RAMDRIVE.SYS  that  created  the  virtual  disk,  the  drive  letter  assigned  to  the  disk, 
and  the  characteristics  of  the  disk. 

RAMDrive:  Above  Board  Memory  Manager  not  present 

The  /A  switch  was  used  in  the  command  line  and  the  Lotus/Intel/Microsoft  Expanded 
Memory  Manager  is  not  present  in  the  system.  Place  the  DEVICE  command  that  loads  the 
memory  manager  before  the  DEVICE= RAMDRIVE  SYS  commaiVid  in  the  CONFIG.SYS 
file. 

RAMDrive:  Above  Board  Memory  Status  shows  errors 

The  Above  Board  device  driver  is  bad  or  damaged  or  the  board  itself  is  defective.  Consult 
the  Above  Board  manual  or  the  manufacturer. 

RAMDrive:  Computer  must  be  PC-AT,  or  PC-AT  compatible. 

The  /E  switch  was  used  in  the  command  line  and  the  computer  is  not  an  80286-based  IBM 
PC/AT  or  compatible. 

RAMDrive:  Incorrect  DOS  version 

The  version  of  RAMDRIVE.SYS  is  not  compatible  with  the  version  of  MS-DOS  that  is 
running. 

RAMDrive:  Insufficient  memory 

Available  memory  is  insufficient  for  RAMDRIVE.SYS  to  create  a  virtual  drive. 

RAMDrive:  Invalid  parameter 

One  of  the  parameters  supplied  in  the  command  line  is  incorrect  or  is  not  supported  by 
the  computer. 

RAMDrive:  I/O  error  accessing  drive  memory 

The  Expanded  Memory  Manager  device  driver  is  bad  or  damaged  or  the  board  itself  is 
defective.  Consult  the  board's  manual  or  contact  the  manufacturer. 

RAMDrive:  No  extended  memory  available 

The  /E  switch  was  specified  but  the  system  does  not  contain  extended  memory. 
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RECOVER 

Recover  Files 


2.0  and  later 
External  No  Net 


Purpose 

Reconstructs  files  from  a  disk  that  has  developed  unreadable  sectors  or  has  a  damaged 
directory. 

Syntax 

RECOVER  drive: 
or 

RECOVER  [drive][path]filename 
where: 

drive  is  the  letter  of  the  drive  holding  the  disk  with  a  damaged  directory. 

filename  is  the  name  of  the  file  that  will  be  reconstructed,  optionally  preceded  by  a 
drive  and/or  path;  wildcard  characters  are  not  permitted. 

Description 

The  RECOVER  command  partially  rescues  a  file  on  a  disk  that  has  developed  bad  sectors 
by  deleting  the  bad  sectors  from  the  file.  RECOVER  can  also  reconstruct  files  (including 
files  stored  in  subdirectories)  from  a  disk  that  has  a  damaged  directory. 

When  RECOVER  is  used  with  a  filename,  the  file  is  read  allocation  unit  by  allocation  unit; 
unreadable  allocation  units  are  marked  as  bad  and  are  no  longer  allocated  to  the  file.  The 
resulting  file  is  usable,  although  the  data  contained  in  the  bad  allocation  units  is  lost.  (The 
recovered  file  may  or  may  not  be  reusable  by  the  specific  application  that  created  it.)  The 
directory  entry  for  filename  is  also  adjusted  to  reflect  the  sectors  that  were  lost  and  the 
bad  sectors  are  marked  in  the  disk’s  file  allocation  table  so  that  they  are  not  reused  for 
another  file. 

If  a  disk’s  directory  is  damaged,  it  still  may  be  possible  to  recover  all  the  files  on  the  disk 
and  build  a  new  directory  by  using  RECOVER  with  drive  as  the  only  command-line 
parameter.  RECOVER  completely  erases  the  previous  contents  of  the  damaged  directory 
and  constructs  new  directory  entries  for  each  of  the  original  files  by  inspecting  the  disk’s 
file  allocation  table.  The  recovered  files  receive  names  of  the  form  FILEwnnw.REC,  starting 
with  FILEOOOl.REC.  Each  recovered  file’s  size  is  always  a  multiple  of  the  disk  cluster  size, 
so  recovered  files  may  require  editing  to  eliminate  spurious  data  at  the  ends  of  the  files. 

RECOVER  restores  each  subdirectory  as  an  individual  file  that  contains  the  names  of  the 
files  originally  stored  in  it.  The  actual  files  contained  within  those  subdirectories  are  also 
reconstructed,  although  they  are  no  longer  associated  with  the  subdirectory  in  which  they 
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originally  resided.  Restored  files  and  subdirectories,  regardless  of  their  location  on  the 
damaged  disk,  are  placed  in  the  new  root  directory.  If  there  are  more  files  on  the  damaged 
disk  than  can  be  contained  in  the  new  root  directory  (for  example,  more  than  112  for  a 
5.25-inch,  360  KB  floppy  disk),  the  user  must  repeat  the  RECOVER  command  after  copy¬ 
ing  the  already-recovered  files  to  another  disk  and  deleting  them  from  the  damaged  disk. 

Examples 

To  recover  the  file  MENUMGR.C  in  the  current  directory  of  the  current  drive,  type 

C>REC0VER  MENUMGR.C  <Enter> 

To  recover  all  files  on  the  disk  in  drive  B,  which  has  a  damaged  directory,  type 

C>REC0VER  B:  <Enter> 

Messages 

If  f ile(s)  recovered 

When  RECOVER  is  used  on  a  disk  with  a  damaged  directory,  this  informational  message 
is  displayed  at  the  conclusion  of  processing  to  indicate  how  many  files  of  the  form 
FILEww««.REC  were  constructed. 

If  of  n  bytes  recovered 

When  RECOVER  is  used  on  a  damaged  file,  this  informational  message  is  displayed  at  the 
conclusion  of  processing  to  advise  how  many  bytes  of  the  file  were  recovered. 

Cannot  RECOVER  a  Network  drive 

Files  on  a  drive  assigned  to  a  network  cannot  be  recovered. 

File  not  found 

The  file  specified  in  the  command  line  cannot  be  found  or  does  not  exist. 

Incorrect  DOS  version 

The  version  of  RECOVER  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Invalid  drive  or  file  name 

An  invalid  drive  letter  was  specified  or  the  filename  contains  a  wildcard. 

Invalid  number  of  parameters 

More  than  one  drive  letter  or  filename  was  specified  in  the  command  line. 

Press  any  key  to  begin  recovery  of  the 
file(s)  on  driveX 

This  prompt  message  gives  the  user  the  opportunity  to  change  disks  after  the  RECOVER 
program  is  loaded  but  before  processing  begins. 

Warning  -  directory  full 

New  directory  entries  for  the  reconstructed  files  cannot  be  created  because  the  root  direc¬ 
tory  is  full.  Copy  the  recovered  files  to  another  disk,  delete  them  from  the  damaged  disk, 
and  then  repeat  the  RECOVER  command  on  the  damaged  disk. 
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RENAME  or  REN  1.0  and  later 

Change  Filename  internal 


Purpose 

Changes  the  name  of  a  file  or  set  of  files. 

Syntax 

RE]^KME[drive'][path\oldnaine  neumame 
or 

RE^[drive'][path]oldname  neumame 
where: 

oldname  is  the  name  of  an  existing  file  or  set  of  files,  optionally  preceded  by  a  drive 
and/or  path;  wildcard  characters  are  permitted. 
newname  is  the  new  name  to  be  assigned  to  oldname\  wildcard  characters  are  per¬ 
mitted,  but  a  drive  and/or  path  cannot  be  specified. 

Description 

The  RENAME  command  changes  the  name  of  an  existing  file  or  set  of  files.  It  does  not 
make  copies  of  files  or  move  files  from  one  location  in  the  disk's  directory  structure  to 
another  or  from  one  drive  to  another. 

The  oldname  parameter  can  refer  to  a  single  file  or  can  include  wildcards  to  specify  a  set 
of  files;  a  drive  and  path  can  be  included  as  part  of  oldname. 

The  netuname  parameter  specifies  the  new  name  to  be  given  to  the  file  or  files;  it  cannot 
include  a  drive  or  path.  A  wildcard  in  neumame  causes  that  portion  of  the  original  file¬ 
name  to  be  left  unchanged.  If  the  new  name  for  a  file  is  the  same  as  the  name  of  an  exist¬ 
ing  file,  RENAME  terminates  with  an  error  message. 

Examples 

To  rename  the  file  REVS.DOC,  located  in  the  current  directory  of  the  current  drive,  to 
CHANGES.TXT,  type 

C>RENAME  REVS.DOC  CHANGES.TXT  <Enter> 

or 

C>REN  REVS.DOC  CHANGES.TXT  <Enter> 

To  rename  all  files  with  a  .DOC  extension  in  the  \ SOURCE  directory  on  the  disk  in  drive  D 
to  have  a  .TXT  extension,  type 

C>REN  D:\S0URCE\* .DOC  *.TXT  <Enter> 
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Messages 

Duplicate  file  name  or  File  not  found 

The  new  name  specified  for  a  file  already  exists  or  a  file  with  the  old  name  cannot  be 
found  or  does  not  exist. 

Invalid  directory 

The  command  line  included  a  reference  to  a  directory  that  is  invalid  or  does  not  exist. 

Invalid  drive  specification 

The  command  line  included  a  reference  to  a  disk  drive  that  is  invalid  or  does  not  exist  in 
the  system. 

Invalid  number  of  parameters 

The  command  line  included  too  few  or  too  many  filenames. 

Invalid  parameter 

The  neumame  parameter  in  the  command  line  included  a  drive  and/or  path. 
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REPLACE  32 

update  Files  External 


Purpose 

Selectively  adds  or  replaces  files  on  a  disk. 

Syntax 

REPLACE  [drive']pathnaine  [driveMpath]  [/A][/D][/P][/R][/S][/W] 
where: 
pathname 

drivepath 

/A 

/D 

/P 
/R 
/S 

/W 

Description 

The  REPLACE  utility  allows  files  to  be  updated  easily  to  more  recent  versions.  REPLACE 
examines  the  source  and  destination  directories  and,  depending  on  the  switches  used  in 
the  command  line,  selectively  updates  matching  files  or  copies  only  those  files  that  exist 
on  the  source  disk  but  not  the  destination  disk. 

The  pathname  parameter  (the  source)  specifies  the  name  and  location  of  the  files  to  be 
transferred  (optionally  preceded  by  a  drive);  wildcards  are  permitted  in  the  filename.  The 
drivepath  parameter  (the  destination)  specifies  the  location  of  the  files  to  be  replaced 
and  can  consist  of  a  drive,  a  path,  or  both.  If  only  a  drive  is  specified  as  the  destination, 
REPLACE  assumes  the  current  directory  of  the  disk  in  that  drive.  If  the  destination  is  omit¬ 
ted  completely,  REPLACE  assumes  the  current  drive  and  directory.  The  /S  switch  causes 
REPLACE  to  also  search  all  subdirectories  of  the  destination  directory  for  files  to  be 
replaced. 

The  A,  /D,  and  /P  switches  allow  selective  replacement  of  files  on  the  destination  disk. 
When  the  A  switch  is  used,  REPLACE  transfers  only  those  files  on  the  source  disk  that  do 
not  exist  in  the  destination  directory.  When  the  /D  switch  is  used,  REPLACE  transfers  only 


is  the  name  and  location  of  the  source  files  to  be  transferred,  optionally 
preceded  by  a  drive;  wildcard  characters  are  permitted  in  the  filename, 
is  the  destination  for  the  file  being  transferred;  filenames  are  not  permit¬ 
ted  in  the  destination  parameter. 

transfers  only  those  source  files  that  do  not  exist  at  the  destination  (cannot 
be  used  with  /S  or  /D). 

transfers  only  those  source  files  with  a  more  recent  date  than  their  destina¬ 
tion  counterparts  (cannot  be  used  with  A), 
prompts  the  user  for  confirmation  before  each  file  is  transferred, 
allows  REPLACE  to  overwrite  destination  read-only  files, 
searches  all  subdirectories  of  the  destination  directory  for  a  match  with 
the  source  files  (cannot  be  used  with  A). 

causes  REPLACE  to  wait  for  the  disk  to  be  changed  before  transferring 
files. 
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those  source  files  that  match  the  destination  filenames  but  have  a  more  recent  date  than 
their  destination  counterparts.  (The  /D  switch  is  not  available  with  the  PC-DOS  version  of 
REPLACE.)  The  /P  switch  causes  REPLACE  to  prompt  the  user  for  confirmation  before 
each  file  is  transferred. 

The  /R  switch  allows  the  replacement  of  read-only  as  well  as  normal  files.  If  the  /R  switch 
is  not  used  and  one  of  the  destination  files  that  would  otherwise  be  replaced  is  marked 
read-only,  the  REPLACE  program  terminates  with  an  error  message.  (REPLACE  cannot  be 
used  to  update  hidden  or  system  files.) 

The  / W  switch  causes  REPLACE  to  pause  and  wait  for  the  user  to  press  any  key  before 
beginning  the  transfer  of  files.  This  allows  the  user  to  change  disks  in  floppy-disk  systems 
with  no  fixed  disk  and  in  those  cases  where  the  REPLACE  program  itself  is  present  on 
neither  the  source  nor  the  destination  disk. 

Return  Codes 

0 
1 
2 
3 
5 

8 
15 

Other 

Examples 

To  replace  the  files  in  the  directory  \  SOURCE  on  the  current  drive  with  all  matching  files 
on  the  disk  in  drive  A  that  have  a  more  recent  date,  type 

OREPLACE  A:*.*  \SOURCE  /D  <Enter> 

To  transfer  from  the  disk  in  drive  A  only  those  files  that  are  not  already  present  in  the  cur¬ 
rent  directory,  type 

OREPLACE  A:*.*  /A  <Enter> 

Messages 

If  File(s)  added 

After  the  replacement  operation  is  completed,  if  the  /A  switch  was  used  in  the  command 
line,  REPLACE  displays  the  total  number  of  files  added. 

If  File(s)  replaced 

After  the  replacement  operation  is  completed,  REPLACE  displays  the  total  number  of  files 
processed. 


The  REPLACE  operation  was  successful. 

An  error  was  found  in  the  REPLACE  command  line. 

No  matching  files  were  found  to  replace. 

The  source  or  destination  path  was  invalid  or  does  not  exist. 

One  of  the  files  to  be  replaced  was  marked  read-only  and  the  /R  switch  was 
not  included  in  the  command  line. 

Memory  was  insufficient  to  run  the  REPLACE  command. 

An  invalid  drive  was  specified  in  the  command  line. 

Standard  MS-DOS  error  codes  (returned  on  a  failed  Interrupt  21H  file-function 
request). 
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Access  denied  ^pathname" 

One  of  the  files  to  be  replaced  on  the  destination  disk  is  marked  read-only  and  the  /R 
switch  was  not  included  in  the  command  line. 

Add  pathname?  (Y/N) 

The  /K  and  /P  switches  were  specified  in  the  command  line  and  REPLACE  prompts  the 
user  for  confirmation  before  adding  each  file. 

Adding  pathname 

The  A  switch  was  specified  in  the  command  line  and  REPLACE  displays  the  name  of  each 
file  it  adds. 

File  cannot  be  copied  onto  itself  pathname^ 

The  source  and  destination  command-line  parameters  specified  the  same  file  in  the  same 
location. 

Incorrect  DOS  Version 

The  version  of  REPLACE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insufficient  disk  space 

The  destination  disk  does  not  have  enough  available  space  to  hold  the  files  being  added  or 
replaced. 

Insufficient  memory 

The  system  does  not  have  enough  RAM  available  to  process  the  REPLACE  command. 

Invalid  drive  specification  'Y:’ 

The  command  line  specified  a  disk  drive  that  is  invalid  or  does  not  exist  in  the  system. 

Invalid  parameter  ^switch" 

The  command  line  included  a  switch  that  is  not  supported  by  the  REPLACE  command. 

No  files  added 

The  /A  switch  was  used  and  the  specified  file(s)  already  exist  on  the  destination  disk. 

No  files  found  pathname^ 

The  files  to  be  added  or  replaced  on  the  destination  disk  were  not  found  on  the  source 
disk. 

No  files  replaced 

The  files  at  the  destination  are  identical  with  the  files  on  the  source  disk  or  do  not  meet  the 
criteria  specified  by  the  switches. 

Parameters  not  compatible 

The  command  line  included  two  or  more  switches  that  cannot  be  used  together. 

Path  not  Found  pathname" 

The  source  or  destination  parameter  included  a  nonexistent  path  or  directory. 
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Path  too  long 

The  source  or  destination  parameter  included  a  path  element  that  is  too  large  (probably 
because  of  a  missing  backslash  character  [\]). 

Press  any  key  to  begin  adding  f  ile(s) 

The  / W  and  /K  switches  were  specified  in  the  command  line  and  REPLACE  waits  for  the 
user  to  press  a  key  before  proceeding,  allowing  disks  to  be  changed. 

Press  any  key  to  begin  replacing  f ile(s) 

The  / W  switch  was  specified  in  the  command  line  and  REPLACE  waits  for  the  user  to 
press  a  key  before  proceeding,  allowing  disks  to  be  changed. 

Replace  pathname'^  (Y/N) 

The  /P  switch  was  specified  in  the  command  line  and  REPLACE  prompts  the  user  for  con¬ 
firmation  before  replacing  the  file. 

Replacing  pathname 

This  informational  message  indicates  the  progress  of  the  REPLACE  command  by  display¬ 
ing  the  name  of  each  file  as  it  is  being  replaced. 

Source  path  required 

Although  the  destination  parameter  can  usually  be  omitted  and  defaults  to  the  current 
drive  and  directory,  the  source  location  for  the  files  to  be  replaced  must  always  be 
specified. 

Unexpected  DOS  Error  n 

This  message  usually  indicates  a  bad  or  damaged  disk.  Use  the  CHKDSK  command  to  de¬ 
termine  the  problem. 
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RESXORE  2.0  and  later 

Restore  Backup  Files  External 


Purpose 

Restores  files  from  a  disk  created  with  the  BACKUP  command. 

Syntax 

RESTORE  drivel:  [drive2'][pathnaine]  [/K:date]  [/^:date]  [/E\time]  [/L:^/me][/M][/N] 
[/S][/P] 

where: 

drivel  is  the  drive  that  contains  the  backup  files  created  by  the  BACKUP 

command. 

drive2  is  the  drive  to  which  the  backup  files  will  be  restored. 

pathname  is  the  name  of  the  file(s)  to  be  restored  from  drivel\  wildcard  characters 

are  permitted  in  the  filename.  If  a  path  is  used,  a  filename  must  be 
specified. 

restores  files  that  were  modified  on  or  after  date. 
restores  files  that  were  modified  on  or  before  date. 
restores  files  modified  at  or  before  time. 
restores  files  modified  at  or  after  time. 
restores  only  files  modified  since  the  last  backup, 
restores  only  files  that  no  longer  exist  on  the  destination  disk, 
prompts  the  user  for  confirmation  before  restoring  hidden  or  read-only 
files  or  before  overwriting  files  that  have  changed  since  they  were  last 
backed  up . 

restores  all  files  in  the  subdirectories  of  the  specified  directory,  in  addition 
to  the  files  in  the  specified  directory. 

Note:  The  PC-DOS  version  of  RESTORE  supports  only  the  /P  and  /S  switches. 

Description 

The  RESTORE  command  restores  files  from  a  backup  disk  or  directory  created  with  the 
BACKUP  command  to  their  original  location  in  a  directory  structure.  Before  version  3.1, 
the  RESTORE  command  could  restore  files  only  from  one  floppy  disk  to  another  or  from  a 
floppy  disk  to  a  fixed  disk.  With  later  versions,  RESTORE  can  also  restore  files  from  one 
fixed  disk  to  another  or  from  a  fixed  disk  to  a  floppy  disk. 

The  drivel  parameter  specifies  the  source  for  the  backed-up  files.  If  the  source  disk  is  a 
fixed  disk,  the  backup  files  are  always  obtained  from  the  directory  \BACKUR  If  multiple 
floppy  disks  were  used  to  hold  the  backed-up  files,  RESTORE  prompts  the  user  for  each 
disk  as  it  is  required. 


/h:date 

/^:date 

/E'.time 

/Litime 

/M 

/N 

/P 


/S 
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The  destination  can  be  any  combination  of  a  drive,  a  path,  and  a  filename;  the  filename 
can  include  wildcards.  If  the  destination  drive  is  omitted,  MS-DOS  assumes  the  current 
drive.  If  a  path  is  not  specified,  the  files  are  restored  to  the  current  directory.  (Note  that 
files  must  be  restored  to  the  same  directory  they  were  backed  up  from.)  If  a  path  is  speci¬ 
fied,  a  filename  must  be  specified  as  well.  If  neither  a  path  nor  a  filename  is  included  in 
the  command  line,  all  directories,  subdirectories,  and  files  on  the  backup  disk(s)  are 
restored  to  the  destination  disk.  The  /S  switch  can  be  used  to  force  restoration  of  the  files 
in  all  the  subdirectories  of  a  named  directory. 

Files  are  restored  in  the  order  they  were  backed  up,  regardless  of  their  current  order  on  the 
destination  disk.  If  files  with  the  same  name  and  location  already  exist  on  the  destination 
disk,  they  are  replaced  by  the  backup  copies. 

The  RESTORE  program  supports  a  number  of  switches  that  allow  selective  restoration  of 
files  from  the  backup  disk.  The  /K-.date,  /B.date,  /'E.-.time,  and  /L-.time  switches  allow  files 
to  be  restored  based  on  the  time  and/or  date  they  were  backed  up.  The  /M  switch  restores 
only  those  files  that  have  been  changed  on  the  destination  disk  since  the  backup  disk  was 
created.  The  /P  switch  prompts  the  user  before  restoring  a  hidden  or  read-only  file  or  a  file 
that  has  been  changed  since  it  was  last  backed  up. 

The  MS-DOS  and  PC-DOS  RESTORE  programs  are  compatible  except  when  a  /Pedate, 
/'Q-.date,  /Y.\time,  /Utime,  /M,  or/N  switch  is  used.  These  switches  are  not  supported  in  the 
PC-DOS  version. 

Warning:  The  RESTORE  command  should  not  be  used  on  a  disk  drive  affected  by  an 
ASSIGN,  SUBST,  or  JOIN  command. 

Return  Codes 

0  The  restore  operation  was  successful. 

1  No  files  were  found  to  restore. 

2  Some  files  were  not  restored  because  of  a  file-sharing  conflict  (versions  3.0  and  later). 

3  The  restore  operation  was  terminated  by  the  user. 

4  The  program  was  terminated  by  an  unrecoverable  (critical)  hardware  error. 

Examples 

To  restore  the  file  named  MENUMGR.C  from  the  backup  disk  in  drive  A  to  the  directory 
named  \SOURCE  on  the  disk  in  drive  B,  type 

OraSTORE  A:  B:\S00RCE\MEN0MGR.C  <Enter> 

To  restore  all  the  files  on  the  backup  disk  in  drive  A  to  their  original  locations  in  the  direc¬ 
tory  structure  of  drive  C,  type 

ORESTORE  A;  C:\».*  /S  <Enter> 
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To  restore  all  the  files  with  the  extension  .C  from  the  backup  disk  in  drive  A  to  the  directory 
named  XSOURCE  on  drive  C,  requesting  confirmation  for  those  files  that  are  read-only  or 
hidden,  type 

C>RESTORE  A:  C : \SOURCE\* . C  /P  <Enter> 

Messages 

***  Files  were  backed  up  at  on 

This  informational  message  shows  when  the  BACKUP  command  was  used  on  the  backed- 
up  files. 

Not  able  to  restore  file  *** 

The  backup  file  or  the  destination  disk  contains  an  error.  Use  the  CHKDSK  command  to 
determine  the  problem. 

Restoring  files  from  drive  •» 

Diskette:  n 

This  informational  message  indicates  the  progress  of  the  RESTORE  command. 

DOS  2.0  or  later  required 

RESTORE  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

File  creation  error 

The  destination  directory  is  full.  This  usually  occurs  only  if  the  destination  is  the  root 
directory  but  can  also  happen  if  a  file  is  being  restored  to  a  subdirectory  and  the  disk  itself 
is  full. 

Incorrect  DOS  version 

The  version  of  RESTORE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running 

Insert  backup  diskette  n  in  drive  X: 

Strike  any  key  when  ready 

This  message  prompts  the  user  to  insert  the  next  backup  disk  in  sequence.  Disks  used  in 
multidisk  backups  should  always  be  labeled  and  numbered  during  a  BACKUP  operation. 

Insert  restore  target  diskette  in  drive  Jir: 

Strike  any  key  when  ready 

This  prompt  is  displayed  when  files  are  being  restored  to  a  floppy  disk. 

Insufficient  memory 

Available  memory  is  not  sufficient  for  the  RESTORE  program  to  execute. 

Invalid  drive  specification 

The  command  line  included  a  drive  that  is  invalid  or  does  not  exist  in  the  system. 

Invalid  number  of  parameters 

The  command  line  included  too  many  or  too  few  parameters. 

Invalid  parameter 

The  command  line  included  an  invalid  switch  or  other  parameter. 
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Invalid  path 

The  destination  parameter  included  a  path  that  is  invalid  or  does  not  exist. 

Restore  file  sequence  error 

Files  are  being  restored  from  a  multidisk  set  of  backup  disks  and  a  floppy  disk  was  used 
out  of  order. 

Source  and  target  drives  are  the  same 

Files  cannot  be  restored  from  a  drive  to  the  same  drive. 

Source  does  not  contain  backup  files 

The  files  on  the  backup  disk  are  not  in  the  special  format  used  by  the  BACKUP  and 
RESTORE  programs. 

System  files  restored 

Target  disk  may  not  be  bootable 

The  backup  disk  included  copies  of  the  hidden  operating-system  files  MSDOS.SYS  and 
lO.SYS  (or  IBMDOS.COM  and  IBMBIO.COM  in  PC-DOS)  and  these  files  were  restored  to 
the  destination  disk.  The  destination  disk  is  bootable  only  if  these  two  files  are  the  first 
files  on  the  disk  and  lO.SYS  (or  IBMBIO.COM)  is  written  into  contiguous  clusters. 

Target  is  full 

The  destination  disk  is  full  and  no  further  files  can  be  restored. 

Target  is  Non-Removable 

The  disk  to  which  files  are  being  restored  is  not  removable. 

The  last  file  was  not  restored 

The  destination  disk  is  full  or  the  last  file  on  the  backup  disk  was  bad. 

Warning!  Diskette  is  out  of  sequence 
Replace  diskette  or  continue  if  okay 

Files  are  being  restored  from  a  multidisk  set  of  backup  disks  and  a  floppy  disk  was  used 
out  of  order. 

Warning!  IBVLefUenatne 
isahiddenfile 
Replace  the  file  (Y/N)? 

The  backed-up  file  has  the  same  filename  as  a  hidden  file  on  the  destination  disk,  which 
may  be  overwritten.  (This  message  appears  only  if  the  /P  switch  was  used.)  Respond  with 
Y  to  overwrite  the  file  on  the  destination  disk;  respond  with  N  to  leave  the  destination  file 
unchanged  and  continue  the  RESTORE  operation. 

Warning!  TYLeJUename 
is  a  read-only  file 
Replace  the  ffle  (Y/N)? 

The  backed-up  file  has  the  same  name  as  a  read-only  file  on  the  destination  disk,  which 
may  be  overwritten.  (This  message  appears  only  if  the  /P  switch  was  used.)  Respond  with 
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F  to  overwrite  the  file  on  the  destination  disk;  respond  with  N  to  leave  the  destination  file 
unchanged  and  continue  the  RESTORE  operation. 

Warning!  VUefilename 

was  changed  after  it  was  backed  up 

Replace  the  file  (Y/N)? 

Data  has  been  changed  or  added  to  the  destination  file  since  the  backup  disk  was  created 
and  this  data  will  be  lost  if  the  file  is  restored.  (This  message  appears  only  if  the  /P  switch 
was  used.)  Respond  with  Y  to  restore  the  backed-up  file;  respond  with  N  to  leave  the  des¬ 
tination  file  unchanged  and  continue  the  RESTORE  operation. 

Warning!  No  files  were  found  to  restore 

No  files  were  found  on  the  backup  disk  that  matched  the  destination  file  specification. 


922  The  MS-DOS  Encyclopedia 


RMDIRorRD 


RMDIRorRD  2.0  and  later 

Remove  Directory  internal 


Purpose 

Removes  an  empty  directory  from  the  hierarchical  file  structure. 

Syntax 

RMDIR  {drtve-[  [ path]directory_name 


or 


RD  ldrive][path]directory_name 
where: 

direaory_name  is  the  name  of  the  directory  to  be  removed,  optionally  preceded  by 
a  drive  and/or  path. 

Description 

The  RMDIR  command  removes  an  empty  directory  from  a  disk’s  hierarchical  file  struc¬ 
ture.  The  directory  being  deleted  cannot  contain  any  files  or  subdirectories  (except  for  the 
special .  and ..  entries).  The  root  directory  or  current  directory  of  a  disk  cannot  be  deleted. 

If  the  path  parameter  is  used,  it  must  specify  a  valid  existing  path.  If  no  path  is  specified 
and  directory^name  is  not  preceded  by  a  backslash  (\),  MS-DOS  assumes  that  the  direc¬ 
tory  to  be  removed  is  a  subdirectory  of  the  current  directory.  If  no  path  is  specified  and 
directory^name  is  preceded  by  a  backslash,  MS-DOS  assumes  that  the  directory  is  a  sub¬ 
directory  of  the  root  directory.  The  length  of  the  full  path  (including  the  drive  designator 
and  directory  name)  must  not  exceed  63  characters. 

The  RMDIR  command  should  not  be  used  to  remove  subdirectories  from  drives  affected 
by  an  ASSIGN  or  JOIN  command.  A  directory  affected  by  the  SUBST  command  cannot  be 
removed. 

Note:  If  a  directory  contains  files  marked  as  hidden  or  system,  that  directory  cannot  be 
removed  even  though  no  files  appear  to  exist  when  the  directory  contents  are  viewed 
using  the  DIR  command. 

Example 

To  remove  the  empty  directory  \LIB,  which  is  a  subdirectory  of  the  \MSC  directory  on  the 
disk  in  drive  A,  type 


C>RMDIR  A:\MSC\LIB  <Enter> 


or 


C>RD  A:\MSC\LIB  <Enter> 
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Message 

Invalid  path,  not  directory,  or  directory  not  empty 

The  named  directory  cannot  be  deleted  because  it  does  not  exist,  some  element  of  the 
path  to  the  directory  does  not  exist,  or  the  directory  contains  files  or  subdirectories. 


924  The  MS-DOS  Encyclopedia 


SELECT 


SELECT  IBM 

Configure  System  Disk  for  a  Specific  Country  External 


Purpose 

Creates  a  system  disk  with  time,  date,  and  keyboard  configured  for  a  selected  country.  This 
command  is  available  only  with  PC-DOS. 

Syntax 

SELECT  [[drivel']  drive2:[path]]  country  keyboard 
where: 

drivel  is  a  floppy-disk  drive  (A  or  B)  containing  the  distribution  disk  or,  at 

a  minimum,  the  PC-DOS  system  files,  COMMAND.COM,  and  the  FORMAT 
and  XCOPY  utilities  (default  =  drive  A)  (version  3.2). 
drive2  is  the  drive  containing  the  disk  to  receive  the  PC-DOS  system  files  and 

country  information  and  can  include  a  path  (default  =  drive  B)  (version 
3.2). 

country  is  a  code  from  the  table  below  that  controls  the  time,  date,  and  currency 

formats. 

keyboard  is  a  code  from  the  table  below  that  controls  the  keyboard  configuration. 


Country 

Country 

Code 

Keyboard 

Co^ 

Australia 

061 

* 

Belgium 

032 

♦ 

Canadian  French 

002 

♦ 

Denmark 

045 

* 

Finland 

358 

* 

France 

033 

FR 

West  Germany 

049 

GR 

Israel 

972 

* 

Italy 

039 

IT 

Middle  East 

785 

* 

Netherlands 

031 

♦ 

Norway 

047 

* 

Portugal 

351 

* 

Spain 

034 

SP 

Sweden 

046 

♦ 

Switzerland 

041 

* 

(more) 
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Country 

Keyboard 

Country 

Code 

Code 

United  Kingdom 

044 

UK 

United  States 

001 

US 

•Available  only  in  version  3.2  and  may  be  supplied  on  a  separate  floppy  disk. 


Description 

The  SELECT  utility  allows  the  user  to  create  a  bootable  system  disk  configured  for  a  par¬ 
ticular  country’s  keyboard  layout  and  date,  time,  and  currency  formats  without  performing 
these  steps  separately. 

Version  3.2  of  SELECT  uses  the  FORMAT  command  to  format  the  disk  in  drive2,  then  uses 
the  XCOPY  command  to  copy  all  files  on  the  disk  in  drivel  (including  the  hidden  system 
files)  to  drive2.  If  a  country  configuration  other  than  one  of  the  six  KEYB;c.jr  utilities  sup¬ 
plied  on  the  distribution  disk  is  specified,  SELECT  prompts  the  user  to  insert  the  disk  con¬ 
taining  the  appropriate  file. 

Versions  3.0  and  3.1  of  SELECT  use  the  DISKCOPY  program  to  copy  all  files  on  the  disk  in 
drive  A  (including  the  hidden  system  files)  to  the  disk  in  drive  B,  formatting  the  disk  if 
necessary. 

All  versions  then  add  the  appropriate  CONFIG.SYS  and  AUTOEXEC.BAT  files  to  the  new 
disk  to  configure  PC-DOS  for  use  with  the  specified  keyboard  and  country  configuration. 
The  specified  configuration  does  not  take  effect  until  the  computer  is  turned  on  or 
restarted  using  the  new  disk. 

Examples 

To  create  a  PC-DOS  system  disk  configured  for  West  Germany  using  version  3.0  or  3.1, 
place  a  copy  of  the  original  PC-DOS  distribution  disk  in  drive  A  and  a  blank  disk  in  drive 
B;  then  type 

A>seleCT  049  GR  <Enter> 

During  the  copy  operation,  the  usual  DISKCOPY  prompts  and  messages  are  displayed. 
When  the  copy  operation  is  complete,  the  two  disks  are  compared  using  DISKCOMP,  pro¬ 
ducing  the  usual  DISKCOMP  prompts  and  messages.  The  resulting  disk  includes  all  the 
files  from  the  distribution  disk  (including  the  hidden  system  files),  a  CONFIG.SYS  file  that 
contains  the  line 

COUNTRY=049 

and  an  AUTOEXEC.BAT  file  that  contains  the  following  lines: 

KEYBGR 

ECHO  OFF 

CLS 

DATE 

TIME 

VER 
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To  create  a  PC-DOS  system  disk  configured  for  West  Germany  using  version  3.2,  place  a 
copy  of  the  original  PC-DOS  distribution  disk  in  drive  A  and  a  blank  disk  in  drive  B;  then 
type 

A>seleCT  049  GR  <Enter> 

SELECT  first  uses  the  FORMAT  command  to  format  the  disk  in  drive  B,  then  uses  XCOPY 
to  copy  all  files  on  the  distribution  disk  (including  the  system  files),  and  finally  creates  a 
CONFIG.SYS  file  that  contains  the  line 

COUNTRY=049 

and  an  AUTOEXEC.BAT  file  that  contains  the  following  lines: 

PATH  \; 

KEYBGR 

ECHO  OFF 

CLS 

DATE 

TIME 

VER 

Messages 

Cannot  cxccuteXi  fUename 

One  of  the  files  needed  by  SELECT  (FORMAT,  DISKCOPY,  DISKCOMP,  or  XCOPY)  is  not 
on  the  source  disk  or  is  a  version  that  is  not  compatible  with  the  version  of  PC-DOS  that  is 
running. 

File  creation  error 

The  root  directory  of  the  destination  disk  is  full  or  unable  to  contain  any  more  files  or  one 
of  the  files  being  created  has  the  same  name  as  a  directory  already  on  the  destination  disk. 

Incorrect  DOS  version 

The  version  of  SELECT  is  not  compatible  with  the  version  of  PC-DOS  that  is  running  (ver¬ 
sion  3.2). 

Incorrect  number  of  parameters 

Too  many  or  too  few  parameters  were  specified  in  the  command  line  or  a  separator  char¬ 
acter  was  omitted  between  two  parameters  (version  3.2). 

Insert  DOS  diskette  in  drive  A: 

Strike  any  key  when  ready 

This  message  prompts  the  user  to  insert  the  distribution  disk  containing  the  system  files 
and  COMMAND.COM  into  drive  A  (version  3.2). 

Insert  KEYBarar.COM  diskette  in  drive  JT: 

Strike  any  key  when  ready 

The  user  responded  Y  to  a  previous  prompt  asking  if  KEYBjca:  is  on  another  disk.  This 
message  prompts  the  user  to  insert  that  disk  into  the  specified  drive  (version  3.2). 
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Insert  target  diskette  in  drive  A: 

Strike  any  key  when  ready 

This  message  prompts  the  user  to  insert  the  disk  that  will  become  the  country-specific  sys¬ 
tem  disk  into  drive  A  (versions  3.0  and  3.1). 

Insert  target  diskette  in  drive  B: 

Strike  any  key  when  ready 

This  message  prompts  the  user  to  insert  the  disk  that  will  become  the  country-specific  sys¬ 
tem  disk  into  drive  B  (version  3.2). 

Invalid  country  code 

The  country  code  given  in  the  command  line  is  not  supported  by  this  version  of  PC-DOS 
or  is  not  a  valid  country  code. 

Invalid  drive  specification 

One  of  the  drives  specified  in  the  command  line  is  invalid  or  does  not  exist  in  the  system 
(version  3.2). 

Invalid  keyboard  code 

The  keyboard  code  given  in  the  command  line  is  not  supported  by  this  version  of  PC-DOS 
or  is  not  a  valid  keyboard  code. 

Invalid  parameter 

One  of  the  parameters  specified  in  the  command  line  is  invalid  or  is  not  supported  by  the 
version  of  SELECT  that  is  running  (version  3.2). 

Invalid  path 

The  path  specified  for  drive2  is  invalid,  contains  invalid  characters,  or  is  longer  than  63 
characters  (version  3.2). 

Is  KEYBxar.COM  on  another 
diskette  (Y/N)? 

The  keyboard  reconfiguration  file  for  the  specified  country  is  not  on  the  source  disk. 
Respond  with  Y  to  cause  SELECT  to  prompt  for  the  disk  containing  the  keyboard  file  after 
the  FORMAT  operation  is  completed;  respond  with  N  to  terminate  the  SELECT  command 
(version  3.2). 

Keyboard  routine  not  found. 

The  user  responded  to  a  previous  prompt  asking  if  KEYBxxis  on  another  disk 

(version  3.2). 

SELECT  is  used  to  install  DOS  the  first 
time.  Select  erases  everything  on  the 
specified  target  and  then  installs  DOS. 

Do  you  want  to  continue  (Y/N)? 

This  message  warns  the  user  that  the  specified  disk  will  be  formatted  and  all  files  on  the 
source  disk  will  be  copied  over.  Respond  with  Y  to  continue;  respond  with  N  to  terminate 
the  SELECT  command  (version  3.2). 
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Unable  to  copy  keyboard  routine 

An  error  occurred  while  the  KEYBxx:.COM  program  was  being  copied.  Use  the  CHKDSK 
command  to  check  the  keyboard  program  on  the  source  disk  for  damage  (version  3.2). 

Unable  to  create  directory 

The  directory  specified  in  the  command  line  was  not  created  because  a  directory  with  the 
same  name  already  exists  on  the  destination  disk,  the  root  directory  of  the  destination  disk 
is  full,  one  of  the  directory  names  specified  in  the  path  does  not  exist,  or  a  file  with  the 
same  name  already  exists  (version  3.2). 
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SET 

Set  Environment  Variable 


2.0  and  later 
Internal 


Purpose 

Defines  an  environment  variable  and  a  string  that  is  its  value. 

Syntax 

SET  [name^value] 
or 

SET  narne^ 
where: 

name  is  a  string  of  characters  that  defines  an  environment  variable;  lowercase  letters 
are  automatically  converted  to  uppercase. 

value  is  a  string  of  characters,  a  pathname,  or  a  filename  that  defines  the  current 
value  of  name\  no  case  conversion  is  made  for  value. 

Description 

The  environment  is  a  series  of  null-terminated  ASCII  (ASCIIZ)  strings  that  contains  envi¬ 
ronment  variables  and  their  values.  (An  environment  variable  associates  a  string  consisting 
of  a  filename,  a  pathname,  or  other  literal  data  with  a  symbolic  name  that  can  be  refer¬ 
enced  by  programs.  The  form  of  the  association  is  naine==  value!)  The  original,  or  master, 
environment  belongs  to  the  command  processor  and  is  established  when  the  system  is 
turned  on  or  restarted.  When  a  program  is  subsequently  executed  by  the  command  pro¬ 
cessor  or  by  another  program,  the  new  program  inherits  a  private  copy  of  its  parent’s 
environment. 

The  SET  command  enables  the  user  to  add,  change,  or  delete  an  environment  variable 
from  the  command  processor’s  environment.  If  value  is  not  included  in  the  SET  com¬ 
mand,  MS-DOS  deletes  the  environment  variable  name  from  the  environment.  If  the  SET 
command  is  issued  with  no  parameters,  MS-DOS  displays  the  values  of  all  the  variables  in 
the  environment. 

With  MS-DOS  versions  2.x  and  3.x,  two  particular  variables  are  always  found  in  an  envi¬ 
ronment:  PATH  and  COMSPEC.  These  variables  are  initialized  during  the  system  startup 
process  and  tell  COMMAND.COM  which  subdirectories  to  search  for  executable  files  and 
where  to  find  the  transient  portion  of  COMMAND.COM  for  reloading  (versions  3.0  and 
later).  (By  default,  PATH  is  a  null  string  and  therefore  searches  only  the  current  or  speci¬ 
fied  directory.)  These  special  environment  variables  are  influenced  by  the  PATH  and 
SHELL  commands,  respectively,  but  can  also  be  changed  with  SET  commands.  Note, 
however,  that  changing  the  value  of  COMSPEC  with  SET  will  serve  no  useful  purpose — 
changing  to  a  different  command  processor  must  be  done  using  an  appropriate  SHELL 
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command  in  the  CONFIG.SYS  file  (the  system  must  be  restarted  for  it  to  take  effect).  Note 
also  that  it  is  not  necessary  to  use  the  SET  command  with  the  PATH  or  PROMPT  com¬ 
mands — MS-DOS  will  automatically  add  their  new  values  to  the  environment  if  they  are 
changed. 

The  environment,  which  can  be  as  large  as  32  KB,  can  be  an  effective  source  of  global  con¬ 
figuration  information  to  executing  programs.  For  instance,  the  Microsoft  C  Compiler  and 
Microsoft  Object  Linker  use  environment  variables  to  locate  include  and  object  library 
files.  Environment  variables  can  also  be  referenced  as  replaceable  parameters  in  batch 
files,  using  the  form  %name%. 

Under  normal  circumstances,  MS-DOS  expands  the  environment  as  necessary  when  SET 
commands  are  entered.  However,  when  a  batch  file  is  being  interpreted  or  when 
terminate-and-stay-resident  (TSR)  utilities  have  been  loaded,  the  size  of  the  command  pro¬ 
cessor’s  environment  becomes  fixed.  Under  these  circumstances,  a  SET  command  may 
result  in  the  error  message  Out  of  environment  space. 

With  version  3  2,  the  initial  size  of  the  environment  can  be  increased  either  by  using  the 
COMMAND  command  with  the  /P  and  /E:  nnnn  switches  at  the  system  prompt  or  by  in¬ 
cluding  a  SHELL  command  specifying  COMMAND.COM  followed  by  the  /E:  nnnn  switch 
in  the  CONFIG.SYS  file.  See  USER  COMMANDS:  command;  config.sys:  shell. 

Examples 

To  define  the  environment  variable  USER  and  set  its  value  to  FRED,  type 

OiSET  USER=FRED  <Enter> 

To  change  the  value  of  the  environment  variable  USER  \o  SALLY,  type 

OSET  USER=SALLY  <Enter> 

To  delete  the  environment  variable  USER  and  its  value  from  the  environment,  type 

OSET  USER=  <Enter> 

To  display  all  the  environment  variables,  type 

OSET  <Enter> 

The  output  of  this  command  will  be  in  the  following  form: 

COMSPEC=C : \D0S3\C0MMAND . COM 
PROMPT=$p$_$n$g 

PATH=D :  \BIN;  C ;  \D0S3 ;  C :  \WP\WORD;  C :  \ASM;  C ;  \MSC\BIN 

INCLUDE=c : \msc\ include; c : \windows\lib 

LIB=c: \msc\lib;c: \windows\lib 

TMP=c : \temp 

PCF32=c : \forth\pc32 

PROCOMM=c : \procomm\ 
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Message 

Out  of  environment  space 

The  command  processor’s  environment  is  full  and  cannot  be  expanded  (usually  because 
the  SET  command  was  issued  from  a  batch  file  or  the  system  has  terminate-and-stay- 
resident  [TSR]  utilities  installed). 
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SHARE  3.0  and  later 

Install  File-Sharing  Support  External 


Purpose 

Loads  the  resident  file-sharing  support  module  required  by  Microsoft  Networks. 

Syntax 

SHARE  [/F:n]  [/L:«] 
where: 

/F:  n  allocates  n  bytes  of  memory  to  hold  file-sharing  information  (default  =  2048). 

/L:  w  configures  support  for  n  simultaneous  file-region  locks  (default  =  20). 

Description 

The  code  that  supports  file  sharing  and  locking  in  a  networking  environment  is  isolated  in 
the  user-installable  SHARE  module.  After  SHARE  is  loaded,  MS-DOS  checks  all  read  and 
write  requests  against  the  file-sharing  module.  On  personal  computers  that  do  not  utilize 
network  services,  the  SHARE  module  need  not  be  loaded,  leaving  more  memory  for  ap¬ 
plication  programs. 

The  /F:«  switch  controls  the  amount  of  buffer  space  allocated  for  file-sharing  information. 
Each  open  file  requires  the  length  of  its  full  name,  including  the  path,  plus  some  overhead; 
the  average  pathname  is  approximately  20  bytes  long.  If  the  /F:  n  switch  is  not  included  in 
the  command  line,  the  buffer  size  defaults  to  2048  bytes  (sufficient  for  approximately  100 
files  with  pathnames  of  average  length). 

The  /L:  w  switch  controls  the  number  of  entries  to  be  allocated  for  an  internal  table  con¬ 
taining  file-locking  information.  Each  active  lock  on  a  region  of  a  file  occupies  one  entry  in 
the  table.  If  the  /L:  n  switch  is  absent,  the  default  is  support  for  20  simultaneously  active 
locks. 

Example 

To  install  the  file-sharing  support  module,  allocating  4096  bytes  of  space  for  file-sharing 
information  and  40  file-region  locks,  type 

C>SHARE  /F:4096  /L:40  <Enter> 

Messages 

Incorrect  DOS  version 

The  version  of  SHARE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Incorrect  parameter 

The  command  line  included  an  invalid  switch. 
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Not  enough  memory 

System  memory  is  insufficient  to  load  the  SHARE  module  or  to  reserve  the  designated  file¬ 
sharing  information  space  or  file-region  locks. 

SHARE  already  installed 

The  SHARE  command  has  already  been  executed  since  the  system  was  turned  on  or 
restarted;  additional  executions  have  no  effect. 
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Alphabetic  Sort  Filter 


2.0  and  later 
External 


Purpose 

Reads  records  from  standard  input,  sorts  them  alphabetically,  and  writes  the  sorted  records 
to  standard  output. 

Syntax 

SORT  [/R][/+co/Mmw] 
where: 

/R  specifies  a  reverse,  or  descending,  alphabetic  sort. 

/^column  specifies  the  first  column  to  be  used  for  sorting  each  line  (default  =  1). 

Description 

The  SORT  program  is  a  filter  that  reads  lines  from  standard  input  until  an  end-of-file 
marker  is  reached,  sorts  the  lines  into  alphabetic  order,  and  writes  the  sorted  lines  to  stan¬ 
dard  output. 

Standard  input  defaults  to  the  keyboard;  standard  output  defaults  to  the  video  display. 
Because  standard  input  can  be  redirected,  the  SORT  filter  can  also  accept  input  from  an¬ 
other  character  device,  a  file,  or  the  piped  output  of  another  program  or  filter.  (The  most 
common  use  of  SORT  is  to  sort  the  redirected  input  from  an  ASCII  text  file.)  Similarly,  the 
output  of  SORT  can  be  redirected  to  any  character  device  or  file  or  can  be  piped  to  another 
program. 

SORT  normally  orders  the  lines  of  the  input  text  stream  alphabetically  using  the  entire  line, 
starting  with  column  1  as  the  sort  key.  Tab  characters  are  not  expanded  to  spaces.  If  the 
character  in  the  sort-key  column  of  one  line  is  identical  with  the  character  in  the  sort-key 
column  of  the  next  line,  SORT  checks  the  next  column  to  the  right  to  determine  which  line 
will  go  before  the  other.  If  the  second  columns  are  also  identical,  the  search  continues  to 
the  right  until  a  differing  column  is  found.  The  maximum  amount  of  data  that  can  be 
sorted  is  63  KB. 

The  /R  switch  causes  SORT  to  arrange  the  set  of  lines  in  reverse  alphabetic  order.  The 
/■^column  switch  lets  the  user  specify  a  column  other  than  column  1  as  the  first  sort  key. 

With  versions  2.x,  SORT  arranges  the  input  lines  based  on  the  ASCII  value  of  the  character 
in  each  line’s  sort-key  column;  the  sort  operation  is  therefore  case  sensitive.  With  versions 
3.0  and  later,  SORT  assigns  lowercase  letters  the  same  ASCII  value  as  uppercase  letters; 
hence,  case  is  effectively  ignored.  Depending  on  the  COUNTRY  command  in  effect  isee 
USER  COMMANDS:  CONFIG.SYS:  country),  versions  3.0  and  later  map  accented  characters 
with  ASCII  codes  in  the  range  80H  through  OEIH  (128-225)  to  their  unaccented  equiva¬ 
lents  for  sorting. 
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Warning:  If  the  output  of  the  SORT  command  is  redirected  to  a  file  with  the  same  name  as 
the  input  file,  the  contents  of  the  input  file  may  be  destroyed. 

Examples 

The  examples  in  this  entry  operate  on  an  ASCII  text  file  named  RECORDS.TXT  that  con¬ 
tains  the  following  lines: 

Smith  Seattle 
Adams  New  York 
Zoole  Bellevue 
Jones  Boston 

Each  line  of  the  file  contains  a  person’s  surname,  starting  in  column  1,  and  a  city  name, 
starting  in  column  10. 

To  sort  the  file  RECORDS.TXT  by  surname  and  display  the  sorted  lines  on  standard  output, 
type 

C>S0RT  <  RECORDS.TXT  <Enter> 

This  will  result  in  the  following  display: 

Adams  New  York 
Jones  Boston 
Smith  Seattle 
Zoole  Bellevue 

To  sort  the  file  RECORDS.TXT  by  surname  and  write  the  sorted  lines  into  the  file 
READY.DOC,  type 

OSORT  <  RECORDS.TXT  >  READY.DOC  <Enter> 

To  sort  the  file  RECORDS.TXT  by  surname  in  reverse  alphabetic  order  and  display  the 
sorted  lines  on  standard  output,  type 

C>S0RT  /R  <  RECORDS.TXT  <Enter> 

This  will  result  in  the  following  display: 

Zoole  Bellevue 
Smith  Seattle 
Jones  Boston 
Adams  New  York 

To  sort  the  file  RECORDS.TXT  by  city  name  and  display  the  sorted  lines  on  standard  out¬ 
put,  type 

C>SORT  /+10  <  RECORDS.TXT  <Enter> 

This  will  result  in  the  following  display: 


Zoole 

Bellevue 

Jones 

Boston 

Adams 

New  York 

Smith 

Seattle 
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To  use  SORT  as  a  filter  to  arrange  a  directory  listing  alphabetically,  type 

C>DIR  !  SORT  <Enter> 

To  use  SORT  as  a  filter  to  arrange  a  directory  listing  alphabetically  based  on  the  first  char¬ 
acter  of  each  file’s  extension,  type 

C>DIR  !  SORT  /+10  <Enter> 

Messages 

Invalid  parameter 

One  of  the  parameters  specified  in  the  command  line  is  invalid  or  the  syntax  is  incorrect. 

SORT:  Incorrect  DOS  version 

The  version  of  SORT  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

SORT:  Insufficient  disk  space 

The  output  of  the  SORT  filter  has  been  redirected  to  a  file  and  the  disk  is  full. 

SORT:  Insufficient  memory 

The  available  system  memory  is  insufficient  to  run  the  SORT  program. 
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SUBST  3.1  and  later 

Substitute  Drive  for  Subdirectory  External  No  Net 


Purpose 

Causes  a  drive  letter  to  be  substituted  for  a  directory  name.  SUBST  is  present  in  MS-DOS  to 
support  older  application  programs  that  do  not  accept  pathnames. 

Syntax 

SUBST  [drivel:  [drive2'\ path] 
or 

SUBST  drivel:  /D 

where: 

drivel 
drive2 

path 

/D 

Description 

The  SUBST  command  allows  a  drive  letter  to  be  substituted  for  a  subdirectory  name. 

The  drivel  parameter  can  be  any  valid  drive  letter  except  the  current  drive  or  drive2. 

Drive  letters  A  through  E  are  always  available;  drive  letters  beyond  E  require  that  an  ap¬ 
propriate  LASTDRIVE  command  be  added  to  the  CONFIG.SYS  file  and  the  system  be  re¬ 
started  isee  USER  COMMANDS:  config.sys:  lastdrive). 

After  a  SUBST  command,  the  files  on  the  disk  normally  referenced  by  drivel  are  no  longer 
accessible.  However,  the  files  in  the  location  specified  by  path  can  still  be  referenced  by 
the  usual  methods  (using  their  actual  drive  and  path)  as  well  as  by  the  substituted  drive 
designator. 

If  the  SUBST  command  is  entered  without  parameters,  MS-DOS  displays  the  substitutions 
currently  in  effect. 

Warning:  The  SUBST  command  masks  the  actual  disk-drive  characteristics  from  com¬ 
mands  that  perform  critical  disk  operations.  Therefore,  ASSIGN,  BACKUP,  CHKDSK, 
DISKCOMP,  DISKCOPY,  FDISK,  FORMAT,  JOIN,  LABEL,  and  RESTORE  should  not  be  used 
on  a  drive  affected  by  a  SUBST  command.  CHDIR,  MKDIR,  RMDIR,  and  PATH  commands 
that  include  the  affected  drive  should  be  used  with  caution.  A  network  drive  cannot  be 
named  in  a  SUBST  command. 


is  the  drive  letter  to  be  used  to  reference  the  files  in  path. 

is  a  drive  letter  other  than  drivel  that  can  optionally  precede  the  name  of  the 

subdirectory  being  substituted. 

is  the  subdirectory  to  be  accessed  when  drivel  is  referenced,  optionally  pre¬ 
ceded  by  drive2. 

cancels  the  effect  of  a  previous  SUBST  command  for  drivel. 
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Examples 

To  substitute  drive  B  for  the  directory  C:\ASM\SOURCE,  type 

OSUBST  B:  C:\ASM\SOURCE  <Enter> 

To  display  the  substitutions  currently  in  effect,  type 

C>SUBST  <Enter> 

In  this  case,  the  SUBST  command  displays 

B:  =>  C:\ASM\SOURCE 

To  cancel  the  effect  of  a  previous  SUBST  command  that  substituted  drive  B  for  a  subdirec¬ 
tory,  type 

OSUBST  B:  /D  <Enter> 

Messages 

Cannot  SUBST  a  network  drive 

One  or  both  of  the  drive  parameters  in  the  command  line  referred  to  a  drive  that  is 
assigned  to  a  network. 

DOS  2.0  or  later  required 

SUBST  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Incorrect  DOS  version 

The  version  of  SUBST  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Incorrect  number  of  parameters 

The  command  line  included  too  many  or  too  few  parameters. 

Invalid  parameter 

The  drive  named  in  the  command  line  is  invalid,  does  not  exist,  is  the  default  drive,  or  is 
the  same  as  the  drive  in  the  path  to  be  substituted. 

Not  enough  memory 

The  available  system  memory  is  insufficient  to  run  the  SUBST  command. 

Path  not  found 

An  element  of  the  path  included  in  the  command  line  is  invalid  or  does  not  exist. 
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SYS  1.0  and  later 

Transfer  System  Files  External  No  Net 


Purpose 

Copies  the  hidden  files  that  contain  the  operating  system  from  the  disk  in  the  current  drive 
to  another  formatted  disk. 

Syntax 

SYS  drive: 
where: 

drive  is  the  location  of  the  disk  that  will  receive  the  system  files.  This  parameter  is 

required. 

Description  i 

An  MS-DOS  system  disk  must  contain  three  files  to  be  bootable:  the  two  operating-system 
files  and  the  command  processor.  The  operating  system  itself  is  contained  in  the  files 
lO.SYS  and  MSDOS.SYS  (or  IBMBIO.COM  and  IBMDOS.COM  in  PC-DOS),  which  must  al¬ 
ways  be  the  first  two  files  in  the  disk's  directory.  Both  have  file  attributes  set  for  system 
and  hidden  (all  versions)  and  read-only  (versions  2.0  and  later).  lO.SYS  (or  IBMBIO.COM) 
contains  the  default  set  of  device  drivers  for  the  system;  it  must  occupy  contiguous  sectors 
in  the  disk’s  files  area.  MSDOS.SYS  (or  IBMDOS.COM)  contains  the  kernel  of  the  operating 
system  proper.  The  third  required  file  is  the  shell,  or  command  processor,  which  by 
default  is  COMMAND.COM.  This  is  an  unrestricted  file  and  can  be  located  anywhere  on 
the  disk. 

The  SYS  command  transfers  the  two  operating-system  files  from  the  default  drive  to  the 
specified  destination  disk.  The  destination  disk  that  receives  the  files  must  meet  one  of  the 
following  requirements: 

•  The  disk  is  formatted  but  completely  empty. 

•  The  disk  currently  contains  hidden  MS-DOS  system  files  that  are  large  enough  to 
allow  replacement  by  the  new  system  files. 

•  The  disk  has  been  formatted  with  the  /B  switch  to  reserve  room  for  the  system  files. 
(Note  that  /B  produces  a  disk  with  only  eight  sectors  per  track.) 

If  the  disk  already  contains  the  two  hidden  system  files,  the  SYS  command  can  be  used  to 
transfer  an  equivalent  or  later  version  of  MS-DOS. 

After  the  two  hidden  operating-system  files  are  installed  with  the  SYS  command,  the 
COMMAND.COM  file  (or  another  command  processor)  must  be  transferred  to  the  destina¬ 
tion  disk  with  the  COPY  command.  The  resulting  disk  is  a  bootable  system  disk. 
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Note:  Because  the  two  system  files  have  the  hidden  attribute,  they  do  not  appear  on  a 
directory  listing  produced  by  the  DIR  command.  The  CHKDSK  command  does  report  the 
presence  of  hidden  files  on  a  disk  and  will  list  their  names  if  the  /V  switch  is  used  but  will 
not  list  such  information  as  the  file  size  or  date  and  time  of  creation. 

Example 

To  transfer  a  copy  of  the  system  files  to  the  disk  in  drive  B,  type 

OSYS  B:  <Enter> 

Messages 

Cannot  SYS  to  a  Network  drive 

The  drive  specified  in  the  command  line  is  currently  assigned  to  a  network. 

Destination  disk  cannot  be  booted 

The  hidden  operating-system  files  were  transferred  to  the  destination  disk  but  could  not 
be  placed  in  contiguous  sectors. 

Incompatible  system  size 

The  destination  disk  already  contains  operating-system  files  and  they  are  smaller  than 
those  being  copied. 

Incorrect  DOS  version 

The  version  of  SYS  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insert  destination  disk  in  driveX 
and  strike  any  key  when  ready 

This  message  prompts  the  user  to  insert  the  disk  onto  which  the  operating-system  files 
will  be  copied  into  the  specified  drive. 

Insert  system  disk  in  driveX 
and  strike  any  key  when  ready 

This  message  prompts  the  user  to  insert  a  disk  containing  the  operating-system  files  into 
the  specified  drive. 

Invalid  drive  specification 

The  drive  specified  in  the  command  line  is  invalid  or  does  not  exist  in  the  system. 

Invalid  parameter 

The  command  line  contained  an  invalid  drive  letter. 

No  room  for  system  on  destination  disk 

Contiguous  space  at  the  beginning  of  the  destination  disk  is  insufficient  for  the  operating- 
system  files.  This  can  occur  when  files  already  exist  on  the  destination  disk  or  when  sec¬ 
tions  of  the  disk  are  marked  as  unusable  by  the  FORMAT  command. 

No  system  on  default  drive 

The  disk  in  the  default  drive  does  not  contain  the  two  hidden  system  files.  Replace  the  disk 
with  a  bootable  system  disk. 

System  transferred 

The  operating-system  files  have  been  successfully  transferred  to  the  destination  disk. 
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TIME  1.0  and  later 

Set  System  Time  Internal 

Purpose 

Sets  or  displays  the  system  time.  TIME  is  an  external  command  with  PC-DOS  version  1.0. 

Syntax 

TIME  [hh\mm[\ss[.xx]]] 
where: 

hh  is  hours  (0-23). 

mm  is  minutes  (0-59). 

55  is  seconds  (0-59). 

OCX  is  hundredths  of  a  second  (0-99). 

Note:  No  spaces  are  allowed  between  any  of  the  time  parameters. 

Description 

All  computers  that  run  MS-DOS  have  as  part  of  their  hardware  configuration  a  timer,  or 
clock,  that  maintains  the  current  system  date  and  time.  One  use  of  this  clock,  among 
others,  is  to  insert  the  current  date  and  time  into  a  file’s  directory  entry  when  the  file  is 
created  or  modified. 

The  TIME  command  allows  the  user  to  display  or  modify  the  current  time  that  is  being 
maintained  by  the  system’s  real-time  clock.  TIME  is  also  executed  by  MS-DOS  when  the 
system  is  turned  on  or  restarted,  unless  an  AUTOEXEC.BAT  file  is  on  the  system  disk,  in 
which  case  the  command  is  executed  only  if  it  is  included  in  the  AUTOEXEC.BAT  file. 

On  IBM  PC/ATs  and  compatibles,  the  TIME  command  does  not  permanently  change  the 
system  time  stored  in  the  built-in  battery-backed  clock/calendar;  the  newly  entered  time  is 
lost  when  the  system  is  turned  off  or  restarted.  On  these  machines,  the  SETUP  program 
(found  on  the  Diagnostics  for  IBM  Personal  Computer  AT  disk  or  equivalent)  must  be  used 
to  permanently  alter  the  clock/calendar’s  current  time. 

On  IBM  PCs,  PC/XTs,  and  compatibles  equipped  with  add-on  cards  containing  battery- 
backed  clock/calendar  circuitry,  it  is  usually  necessary  to  run  a  time/date  installation  pro¬ 
gram  (included  with  the  card)  to  set  the  system  date  and  time  from  the  clock/calendar 
on  the  card.  The  TIME  command  generally  has  no  effect  on  these  card-mounted 
clock/calendars. 

The  format  of  times  displayed  by  the  system  depends  on  the  current  country  code,  which 
is  determined  by  the  optional  COUNTRY  command  in  the  CONFIG.SYS  file  {see  USER 
COMMANDS:  CONFIG.SYS:  country).  The  default  display  format  is  the  24-hour  format 
(00:00-23:59). 
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TIME 


Examples 

To  display  the  current  time,  type 

OTIME  <Enter> 

This  results  in  output  of  the  following  form: 

Current  time  is  12:49:04.93 
Enter  new  time: 

To  leave  the  time  unchanged,  press  the  Enter  key. 

To  set  the  system  time  to  8:30  P.M.,  type 

OTIME  20:30  <Enter> 

Messages 

Current  time  is  hhimmxss.xx 

This  informational  message  is  displayed  in  response  to  any  valid  TIME  command. 

Invalid  parameter 

The  delimiter  in  the  time  parameter  included  in  the  command  line  was  not  a  colon  (:)  or  a 
period  (.). 

Invalid  time 
Enter  new  time: 

An  invalid  time,  time  format,  or  delimiter  was  specified  in  the  command  line  or  in 
response  to  the  Enter  new  time:  prompt.  Note  that  no  spaces  are  allowed  around 
delimiters. 
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TREE 


TREE 

Display  Directory  Structure 


3.2 

External 


Purpose 

Displays  the  hierarchical  directory  structure  of  a  disk  and,  optionally,  the  names  of  the 
files  in  each  subdirectory.  This  command  is  included  with  PC-DOS  beginning  with 
version  2.0. 

Syntax 

TREE  [drive{\[/¥] 
where: 

drive  is  the  location  of  the  disk  whose  directory  structure  is  to  be  displayed. 

/F  displays  the  filenames  in  each  directory  in  addition  to  the  directory  names. 

Description 

The  TREE  command  displays  on  standard  output  the  pathname  of  each  directory  on  the 
disk  in  the  specified  drive,  beginning  with  the  subdirectories  of  the  root  directory.  If  a  disk 
drive  is  not  designated,  TREE  assumes  the  current,  or  default,  drive.  The  name  of  each 
directory  is  followed  by  a  list  of  its  subdirectories.  If  the  /F  switch  is  included  in  the  com¬ 
mand  line,  the  names  of  the  files  in  each  subdirectory  are  also  displayed.  (Prior  to  version 
3.1,  the  PC-DOS  TREE  command  does  not  list  the  files  in  the  root  directory  if  /F  is  used.) 

The  output  of  the  TREE  command  can  be  redirected  to  another  output  device  or  a  file  or 
can  be  piped  to  another  program. 

Examples 

Assume  that  the  root  directory  of  the  disk  in  drive  B  contains  three  subdirectories: 

\  SOURCE,  \LIBS,  and  \DOC.  The  subdirectory  \ SOURCE  in  turn  contains  two  subdirec¬ 
tories:  \  ASM  and  \  PASCAL.  To  display  the  directory  structure  of  this  disk,  type 

C>TREE  B;  <Enter> 

The  TREE  command  displays  the  following  list: 
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DIRECTORY  PATH  LISTING  FOR  VOLUME  MYDISK 

Path:  B:\SOURCE 

Sub-directories:  ASM 

PASCAL 

Path:  B:\SOURCE\ASM 
Sub-directories:  None 

Path:  B:\SOURCE\PASCAL 
Sub-directories:  None 


Path:  B:\LIBS 
Sub-directories :  None 

Path:  B:\DOC 
Sub-directories:  None 

To  display  the  directory  structure  of  the  disk  in  drive  B  and  also  display  all  files  in  each 
directory,  type 

C>TREE  B:  /F  <Enter> 

To  print  the  directory-structure  listing  of  the  disk  in  drive  B  on  an  attached  printer,  type 

C>TREE  B:  >  PRN  <Enter> 

To  display  the  directory  structure  of  the  disk  in  drive  B  one  screenful  at  a  time,  type 

C>TREE  B:  1  MORE  <Enter> 

For  a  more  compressed  listing  of  all  subdirectories  on  the  disk  in  drive  B,  type 

t:>TREE  B:  !  FIND  "Path:"  <Enter> 

The  output  appears  in  the  following  form: 

Path:  B:\SOURCE 
Path:  B:\SOURCE\ASM 
Path:  B:\SOURCE\PASCAL 
Path:  B:\LIBS 
Path:  B:\DOC 
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Messages 

DOS  2.0  or  later  required 

TREE  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

Incorrect  DOS  version 

The  version  of  TREE  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Invalid  drive  specification 

The  drive  specified  in  the  command  line  is  invalid  or  does  not  exist  in  the  system. 

Invalid  parameter 

The  command  line  contained  a  path  or  filename  in  addition  to  a  disk  drive  or  contained  an 
invalid  switch. 

No  sub-directories  exist 

The  specified  drive  has  no  subdirectories. 
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TYPE  1.0  and  later 

Display  File  Internal 


Purpose 

Sends  the  contents  of  an  ASCII  text  file  to  standard  output. 

Syntax 

TYPE  [drive][path\filenaine 
where: 

filename  is  the  name  of  the  text  file  to  be  displayed,  optionally  preceded  by  a  drive 
and/or  path;  wildcard  characters  are  not  permitted. 

Description 

The  TYPE  command  displays  the  contents  of  a  text  file  on  standard  output  (usually  the 
video  display)  until  it  encounters  an  end-of-file  character  (ASCII  code  1  AH).  Tab  charac¬ 
ters  in  the  file  are  expanded  to  spaces  with  tab  stops  at  each  eighth  character  position.  If  a 
file  contains  characters  with  ASCII  values  less  than  32  or  greater  than  127,  the  resulting  dis¬ 
play  includes  graphics  characters  and  other  unintelligible  information. 

The  output  of  the  TYPE  command  can  be  redirected  to  another  file  or  character  device  or 
can  be  piped  to  another  program. 

Examples 

To  display  the  file  SHELL.C  in  the  directory  \SOURCE  on  the  disk  in  drive  A,  type 

OTYPE  A:\SOURCE\SHELL.C  <Enter> 

To  direct  the  output  of  the  same  file  to  the  printer,  type 

OTYPE  A:\SOURCE\SHELL.C  >  PRN  <Enter> 

The  TYPE  command  can  be  used  with  the  MORE  filter  to  paginate  output.  For  example,  to 
display  the  contents  of  the  file  MENU.  ASM  one  screenful  at  a  time,  type 

OTYPE  MENU. ASM  1  MORE  <Enter> 

Messages 

File  not  found 

The  file  specified  in  the  command  line  cannot  be  found  or  does  not  exist. 

Invalid  drive  specification 

The  drive  specified  in  the  command  line  is  invalid  or  does  not  exist  in  the  system. 

Invalid  path  or  file  name 

The  path  specified  in  the  command  line  is  invalid  or  does  not  exist. 
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VDISK.SYS 

Virtual  Disk 

Purpose 

Creates  a  virtual  disk  in  memory.  This  installable  driver  is  available  only  with  PC-DOS. 

Syntax 

DEVICE=[<^r/t;e:][p<a5//^]VDISK.SYS  [size]  [sector]  [directory]  [/E]  (version  3.0) 

or 

\yENKE=[drive']  [ VDISK.SYS  [size]  [sector]  [directory]  [/E  [:  max]]  (version  3. 1) 

or 

DEVICE=[<in2;^:][p<a5?/2]VDISK.SYS  [comment]  [size]  [comment]  [sector]  [comment] 
[directory]  [/E[: max]]  (version  3.2) 

where: 

comment  is  a  string  of  ASCII  characters  in  the  range  32  through  126,  excluding  the 

slash  character  (/)  (version  3.2). 

size  is  the  size  of  the  virtual  disk  in  kilobytes  (minimum  =  1,  default  =  64). 

sector  is  the  sector  size  in  bytes  (128, 256,  or  512;  default  =  128). 

directory  is  the  maximum  number  of  entries  in  the  virtual  disk’s  root  directory 

(2-512,  default  =  64). 

/E  causes  VDISK  to  use  extended  memory. 

/E:  max  causes  VDISK  to  use  extended  memory  and  sets  the  maximum  number  of 

sectors  (1-8,  default  =  8)  to  transfer  from  extended  memory  at  one  time 
(versions  3.1  and  later). 

Note:  Unless  the  /E  switch  is  used,  the  virtual  disk  is  created  in  conventional  memory. 

Description 

The  VDISK.SYS  installable  device  driver  allows  the  configuration  of  one  or  more  virtual 
disks  (sometimes  referred  to  as  electronic  disks  or  RAMdisks).  A  virtual  disk  is  imple¬ 
mented  by  mapping  a  disk’s  structure — directory,  file  allocation  table,  and  files  area — 
onto  an  area  of  random-access  memory,  rather  than  onto  actual  sectors  located  on  a 
magnetic  recording  medium.  Access  to  files  stored  in  a  virtual  disk  is  very  fast,  because 
no  moving  parts  are  involved  and  the  “disk”  operates  at  the  speed  of  the  system’s  mem¬ 
ory.  (The  VDISK  driver  is  available  only  with  PC-DOS;  a  similar  program  named 
RAMDRIVE.SYS  is  included  with  MS-DOS.) 

Warning:  Because  a  RAMdisk  resides  entirely  in  RAM  and  is  therefore  volatile,  any  infor¬ 
mation  stored  there  is  irretrievably  lost  when  the  computer  loses  power  or  is  restarted. 


IBM 

External 
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VDISK  can  create  a  virtual  disk  in  either  conventional  memory  or  extended  memory.  Con¬ 
ventional  memory  is  the  term  for  the  up-to-640  KB  of  RAM  that  contain  PC-DOS  and  any 
application  programs.  Extended  memory  is  the  term  for  the  memory  at  addresses  above  1 
MB  (lOOOOOH)  that  is  available  on  80286-based  personal  computers  such  as  the  IBM  PC/AT. 

A  virtual  disk  can  be  installed  in  conventional  memory  by  simply  inserting  the  line 
DEVICE=VDISK.SYS  into  the  system’s  CONFIG.SYS  file  and  restarting  the  system.  (If  the 
file  VDISK.SYS  is  not  in  the  root  directory  of  the  startup  disk,  it  may  be  preceded  by  a 
drive  and/or  path.)  A  new  “drive”  then  becomes  available  in  the  system,  with  default 
values  of  64  KB  disk  size,  128-byte  sectors,  and  64  available  directory  entries  (assuming 
there  is  sufficient  memory).  The  virtual  disk  is  assigned  the  next  available  drive  letter 
(which  is  displayed  in  VDISK’s  sign-on  message).  The  drive  letter  assigned  depends  on  the 
number  of  other  physical  and  virtual  disks  in  the  system  and  also  on  the  position  of  the 
DEVICE=VDISK.SYS  line  in  the  CONFIG.SYS  file  relative  to  other  installed  block  devices. 
Available  memory  permitting,  multiple  virtual  disks  can  be  created  by  using  multiple 
DEVICE=VDISK.SYS  lines.  Several  optional  parameters  allow  the  user  to  customize  the 
size  and  configuration  of  the  virtual  disk  and  to  use  extended  memory  if  it  is  available. 

The  size  parameter  specifies  the  amount  of  RAM,  in  kilobytes,  to  be  allocated  to  the  virtual 
disk.  The  default  is  64  KB,  but  any  size  from  1  KB  to  the  total  amount  of  available  memory 
can  be  specified.  If  the  size  specified  is  greater  than  available  memory  or  less  than  1  KB, 
VDISK  ignores  it  and  creates  a  virtual  disk  of  64  KB.  If  necessary,  VDISK  also  adjusts  the 
size  value  to  ensure  that  at  least  64  KB  of  memory  remain  available  in  the  system. 

The  sector  parameter  sets  the  virtual  sector  size  used  within  the  virtual  disk.  The  sector 
value  may  be  128,  256,  or  512  bytes  (default  =  128  bytes).  Selection  of  the  smallest  sector 
size  results  in  a  minimum  of  wasted  virtual  disk  space  per  file  but  also  results  in  somewhat 
slower  transfer  of  data. 

Note:  Physical  disk  devices  in  IBM  PC-compatible  systems  always  use  512-byte  sectors. 

The  directory  parameter  sets  the  number  of  available  entries  in  the  virtual  disk’s  root 
directory.  The  allowed  range  is  2  through  512  (default  =  64).  Each  directory  entry  requires 
32  bytes.  VDISK  rounds  the  number  of  available  directory  entries  up,  if  necessary,  so  that 
an  integral  number  of  sectors  are  assigned  to  the  root  directory. 

The  /E  switch  causes  VDISK  to  use  extended  memory  for  the  virtual  disk,  rather  than  con¬ 
ventional  memory.  This  allows  very  large  virtual  disks  to  be  configured  while  still  leaving 
the  maximum  amount  of  conventional  memory  available  for  use  by  application  programs. 
If  the  /E  switch  is  used  and  extended  memory  is  not  present  in  the  system,  the  VDISK 
driver  will  not  install  itself 

When  /E  is  used  in  the  form  /E\max,  the  variable  max  controls  how  many  virtual  sectors 
can  be  transferred  at  a  time  from  extended  memory.  The  value  of  max  must  be  in  the 
range  1  through  8  (default  =  8).  If  VDISK  operation  appears  to  conflict  with  the  communi¬ 
cations  port  or  other  interrupt-driven  peripheral  devices,  the  max  variable  should  be  set  to 
a  smaller  number.  The  max  option  is  available  only  with  versions  31  and  3  2. 
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Note:  If  VDISK  uses  conventional  memory  for  virtual  disk  storage,  the  memory  cannot  be 
reclaimed  except  by  modifying  the  CONFIG.SYS  file  and  restarting  the  system. 

Examples 

To  create  a  virtual  disk  drive  with  the  default  values  of  64  KB  disk  size,  128-byte  sectors, 
and  64  available  directory  entries,  include  the  command 

DEVICE=VDISK.SYS 

in  the  CONFIG.SYS  file  and  restart  the  system. 

To  create  a  360  KB  virtual  disk  with  512-byte  sectors  and  112  available  directory  entries 
when  the  file  VDISK.SYS  is  located  in  a  directory  named  \BIN  on  drive  C,  include  the 
command 

DEVICE=C:\BIN\VDISK.SYS  360  512  112 

in  the  CONFIG.SYS  file  and  restart  the  system.  The  directory  for  this  virtual  disk  requires 
3584  bytes  (112  entries  *  32  bytes),  or  7  sectors. 

With  version  3.2,  comments  can  be  inserted  between  the  values  to  identify  them.  For  ex¬ 
ample,  to  create  a  1  MB  virtual  disk  drive  in  extended  memory  with  256-byte  sectors  and 
128  directory  entries,  placing  comments  before  the  values  to  identify  them,  include  the 
command 

DEVICE=VDISK.SYS  DISK_SIZE:  1024  SECTOR^SIZE:  256  DIR_ENTRIES:  128  /E 

in  the  CONFIG.SYS  file  and  restart  the  system. 

Messages 

Buffer  size  adjusted 

No  size  value  was  specified  or  the  specified  value  was  larger  than  the  amount  of  available 
memory. 

Directory  entries  adjusted 

No  directory  value  was  specified,  VDISK  adjusted  the  directory  value  up  to  the  nearest 
sector-size  boundary,  or  the  size  value  was  too  small  to  hold  the  file  allocation  table,  the 
directory,  and  two  additional  sectors,  in  which  case  VDISK  adjusted  directory  downward 
until  these  conditions  were  met. 

Invalid  switch  character 

A  slash  character  (/)  was  included  in  a  comment  or  the  /E  switch  was  entered  incorrectly. 

Sector  size  adjusted 

The  sector  value  was  missing  from  the  command  line  or  an  incorrect  value  was  entered; 
therefore,  VDISK  used  the  default  value  of  128  bytes. 
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Transfer  size  adjusted 

A  value  outside  the  range  1  through  8  was  specified  with  the  /lB.\inax  switch;  therefore, 
VDISK  used  the  default  value  of  8. 

VDISK  not  installed  -  Extender  Card  switches 
do  not  match  the  system  memory  size 

The  switch  settings  on  the  extender  card  are  not  correct  or  the  extended  memory  exists  in 
an  expansion  unit,  which  VDISK  is  not  capable  of  using. 

VDISK  not  installed  -  insufficient  memory 

Less  than  64  KB  of  system  memory  remained  after  attempted  installation,  the  /E  switch 
was  specified  and  the  system  does  not  contain  extended  memory,  or  the  amount  of  avail¬ 
able  extended  memory  was  too  small  to  support  the  installation  of  VDISK. 

VDISK  Version  n.nn  virtual  disk X: 

Buffer  size:  If  If  KB 
Sector  size:  If  If  If 
Directory  size:  nnn 
Transfer  size:  If 

VDISK  was  successfully  installed  and  this  message  informs  the  user  of  the  drive  letter 
assigned  to  the  virtual  disk,  the  version  of  VDISK  that  created  the  disk,  and  the  character¬ 
istics  of  the  disk.  The  Transfer  size:  message  appears  only  in  versions  3.1  and  3.2  and  only 
if  the  /E  switch  was  used. 
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VER  2.0  and  later 

Display  Version  internal 


Purpose 

Displays  the  MS-DOS  version  number. 

Syntax 

VER 

Description 

The  VER  command  displays  on  standard  output  (usually  the  video  display)  the  number  of 
the  MS-DOS  version  that  is  running.  The  version  number  is  also  displayed  as  part  of  the 
copyright  notice  when  the  system  is  turned  on  or  restarted,  unless  an  AUTOEXEC.BAT  file 
is  on  the  system  disk.  (The  VER  command  can  be  included  in  the  AUTOEXEC.BAT  file  to 
display  the  version  number,  but  it  will  not  display  the  copyright  information.) 

Examples 

To  display  the  MS-DOS  version  number,  type 

C>VER  <Enter> 

On  a  system  that  is  running  MS-DOS  version  3.2,  the  following  message  is  displayed: 

MS-DOS  Version  3.2 

To  print  the  MS-DOS  version  number  on  an  attached  printer  instead  of  displaying  it  on  the 
screen,  type 

C>VER  >  PRN  <Enter> 
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VERIFY  2.0  and  later 

Set  Verify  Flag  Internal 


Purpose 

Sets  the  system’s  internal  flag  controlling  verification  of  disk  writes. 

Syntax 

VERIFY  [ON [OFF] 

Description 

The  VERIFY  command  sets  or  clears  an  internal  MS-DOS  flag  that  controls  verification  of 
data  written  to  disks.  (The  actual  verification  process  is  usually  carried  out  by  the  device 
driver  and  the  disk-drive  controller.)  The  VERIFY  ON  command  has  the  same  effect  on  a 
global  basis  as  the  /V  switch  has  on  COPY  operations.  (When  VERIFY  is  on,  use  of  the  /V 
switch  with  COPY  has  no  additional  effect.)  VERIFY  ON  remains  in  effect  until  a  program 
turns  it  off  with  a  Set  Verify  system  call  or  until  the  user  types  VERIFY  OFF  at  the  com¬ 
mand  prompt.  The  VERIFY  command  does  not  affect  the  operation  of  character  devices. 

When  the  VERIFY  command  is  entered  without  an  ON  or  OFF,  MS-DOS  displays  the  cur¬ 
rent  state  of  the  system’s  internal  verify  flag.  The  default  setting  of  the  verify  flag  is  off. 

Examples 

To  turn  on  verification  of  disk  writes,  type 

OVERIFY  ON  <Enter> 

To  display  the  current  status  of  the  verify  flag,  type 

C>VERIFY  <Enter> 

Messages 

Must  specify  ON  or  OFF 

The  command  line  contained  an  invalid  parameter. 

VEMFYisoff 

or 

VERIFY  is  on 

No  setting  was  specified  in  the  command  line  and  VERIFY  displays  this  informational 
message  indicating  the  current  status  of  the  verify  flag. 


Section  III:  User  Commands  953 


VOL 


VOL  2.0  and  later 

Display  Disk  Name  Internal 


Purpose 

Displays  a  disk’s  volume  label  if  one  exists. 

Syntax 

VOL  [drive-] 
where: 

drive  is  the  location  of  the  disk  whose  volume  label  is  to  be  displayed. 

Description 

The  VOL  command  displays  a  disk’s  name,  or  volume  label.  If  drive  is  not  included  in  the 
command  line,  the  volume  label  of  the  disk  in  the  current  drive  is  displayed. 

A  volume  label  can  be  assigned  to  a  disk  when  it  is  formatted  by  using  the  /V  switch  with 
the  FORMAT  command.  A  volume  label  can  be  added,  changed,  or  deleted  after  a  disk 
has  already  been  formatted  by  using  the  LABEL  command  (PC-DOS  versions  3.0  and  later, 
MS-DOS  versions  3.1  and  later).  The  CHKDSK,  DIR,  and  TREE  commands  also  display  a 
disk’s  volume  label  as  part  of  their  output. 

Example 

To  display  the  volume  label  for  the  disk  in  the  current  drive,  type 

OVOL  <Enter> 

If  the  disk’s  name  is  HARDDISK,  the  VOL  command  produces  the  following  output: 

Volume  in  drive  C  is  HARDDISK 

Messages 

Invalid  drive  specification 

The  drive  specified  in  the  command  line  is  invalid  or  does  not  exist  in  the  system. 

Volume  in  drive  A*  has  no  label 

The  disk  in  the  current  or  specified  drive  was  not  previously  assigned  a  volume  label  with 
the  FORMAT  or  LABEL  command. 
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XCOPY  32 

Copy  Files  External 


Purpose 

Copies  files  and  directories,  optionally  also  copying  subdirectories  and  the  files  they 
contain. 

Syntax 

XCOPY  source  [destinatiorA[/K\  \/T>\mm-dd-yy\  [/E]  [/M]  [/P]  [/S]  [/V]  [/W] 
where: 
source 

destination 

/A 

/Y:>:mm-dd-yy 

/E 

/M 

/P 
/S 

/V 
/W 

Description 

The  XCOPY  command  copies  one  or  more  source  files  to  one  or  more  destination  files. 
Unlike  the  COPY  command,  however,  a  single  XCOPY  command  can  copy  all  files  con¬ 
tained  in  the  entire  hierarchical  file  structure  of  the  source  disk  to  the  destination  disk, 
creating  a  corresponding  set  of  directories  and  subdirectories  at  the  destination  to  hold  the 
copied  files. 

The  source  parameter  identifies  the  file  or  files  to  be  copied.  It  can  consist  of  any  combina¬ 
tion  of  a  drive,  path,  and  filename  (optionally  including  wildcards)  but  must  include  either 


is  the  name  of  the  file(s)  to  be  copied,  optionally  preceded  by  a 
drive  and/or  path;  wildcard  characters  are  permitted  in  the  file¬ 
name.  If  the  path  is  omitted,  a  drive  letter  must  be  specified;  this 
parameter  is  not  optional. 

is  the  destination  location  and,  optionally,  the  name  for  the  copied 
files,  and  can  be  preceded  by  a  drive;  wildcard  characters  are  per¬ 
mitted  in  the  filename. 

copies  only  those  source  files  with  the  archive  bit  set. 
copies  only  files  modified  on  or  after  the  specified  date.  (The  date 
format  depends  on  the  COUNTRY  command  in  effect,  if  any.) 
copies  empty  subdirectories;  if  this  switch  is  used,  the  /S  switch 
must  also  be  specified. 

copies  only  those  files  with  the  archive  bit  set;  also  turns  off  the 
archive  bit  of  each  source  file  after  it  is  copied, 
prompts  the  user  for  confirmation  before  copying  each  file, 
copies  all  nonempty  subdirectories  of  source  and  the  files  they 
contain. 

performs  read-after-write  verification  of  destination  file(s). 
waits  for  the  user  to  press  a  key  before  copying  any  files,  allowing 
disks  to  be  changed. 
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a  drive  or  a  pathname.  If  only  a  drive  is  specified,  all  files  in  the  current  directory  of  that 
drive  are  copied.  If  a  path  without  a  drive  or  filename  is  specified,  all  files  in  the  named 
directory  are  copied  from  the  current  drive. 

The  destination  parameter  can  also  consist  of  any  combination  of  drive,  path,  and  file¬ 
name.  Unless  only  a  single  file  is  being  copied  and  it  is  also  being  renamed  as  part  of  the 
XCOPY  operation,  destination  is  usually  simply  a  drive  and/or  path  specifying  where  to 
place  the  copied  file.  If  destination  includes  a  filename,  XCOPY  displays  a  message  asking 
if  the  specified  destination  is  a  file  or  a  directory.  Depending  on  the  user’s  response, 
XCOPY  then  either  copies  the  source  file  to  a  destination  file  with  the  specified  name  or 
creates  a  directory  with  the  specified  name  and  copies  the  source  files  into  it.  (Note  that  if 
the  user  responds  that  the  destination  is  to  be  a  file  and  multiple  source  files  were  speci¬ 
fied  in  the  command  line,  only  the  last  source  file  is  copied  to  the  specified  destination.)  If 
no  destination  is  specified,  the  source  file  is  copied  to  a  file  with  the  same  name  in  the  cur¬ 
rent  directory  of  the  current  drive. 

The  /A,  /D:  mm-dd-yy,  /M,  and  /P  switches  allow  selective  copying  of  files.  The  /A  switch 
is  used  to  copy  only  source  files  with  the  archive  bit  set;  the  /M  switch  also  copies  only 
source  files  with  the  archive  bit  set  but  turns  off  each  source  file’s  archive  bit  after  the  file 
is  copied.  The  /D:  mm-dd-yy  switch  is  used  to  copy  files  that  were  modified  on  or  after  a 
selected  date;  the  date  must  be  entered  in  one  of  the  formats  discussed  in  the  entry  for  the 
system’s  DATE  command  or  in  the  format  of  the  COUNTRY  command  currently  in  effect 
(.see  USER  COMMANDS:  config.sys:  country).  The  /P  switch  causes  XCOPY  to  prompt 
the  user  for  confirmation  before  transferring  each  file. 

The  /E  and  /S  switches  allow  an  entire  branch  of  the  source  disk’s  hierarchical  directory 
structure  to  be  copied.  If  the  /S  switch  is  specified,  XCOPY  copies  all  nonempty  subdirec¬ 
tories  of  source,  creating  equivalent  destination  subdirectories,  if  necessary,  to  hold  the 
files.  If  the  /E  switch  is  specified,  XCOPY  also  duplicates  empty  source  subdirectories  in 
the  equivalent  destination  locations.  If  the  /E  switch  is  used,  the  /S  switch  must  also  be 
specified. 

The  /V  switch  causes  a  Verify  call  to  be  issued  on  the  destination  file(s)  to  ensure  that  the 
data  was  written  correctly.  Its  effect  is  equivalent  to  that  of  the  VERIFY  ON  command. 

Finally,  the  /  W  switch  causes  XCOPY  to  wait  for  the  user  to  press  a  key  before  copying  any 
files,  thus  allowing  an  exchange  of  disks  before  the  files  are  transferred.  This  is  useful  in 
systems  without  a  fixed  disk,  because  it  allows  XCOPY  to  be  used  when  the  program  itself 
is  not  on  either  the  source  or  the  destination  disk. 

Note:  With  MS-DOS  versions  of  XCOPY,  the  related  program  MCOPY  can  be  created  by 
simply  copying  the  file  XCOPY.EXE  to  a  file  named  MCOPY.EXE  using  the  following 
command: 

OCOPY  /B  XCOPY.EXE  MCOPY.EXE  <Enter> 

What  distinguishes  MCOPY  from  XCOPY  is  the  program  name;  when  either  program  is 
loaded,  it  looks  at  the  name  under  which  it  was  invoked  and  reconfigures  itself  accord¬ 
ingly.  MCOPY’s  behavior  is  similar  to  XCOPY’s,  except  that  MCOPY  automatically 
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determines  whether  the  name  specified  as  the  destination  is  a  file  or  a  directory  according 
to  the  following  rules: 

•  If  the  source  is  a  directory,  the  specified  destination  is  a  directory. 

•  If  the  source  includes  multiple  files,  the  specified  destination  is  a  directory. 

•  If  the  destination  name  ends  with  a  backslash  character  (\),  the  specified  destination 
is  a  directory. 

MCOPY  supports  all  the  XCOPY  switches. 

Not  all  implementations  of  XCOPY  can  be  renamed  to  MCOPY  and  function  accordingly. 
The  PC-DOS  version  of  XCOPY,  for  example,  does  not  support  this  feature. 

Return  Codes 

0  No  errors  were  detected  during  the  copy  operation. 

1  No  files  were  found  to  copy. 

2  The  copy  operation  was  terminated  by  a  Ctrl-C  or  Ctrl-Break. 

4  Initialization  error  occurred:  not  enough  memory,  file  not  found,  or  command-line 
syntax  error. 

5  The  copy  operation  was  terminated  by  an  A  response  to  an  Abort,  Retry,  Ignore? 
prompt. 

Examples 

To  copy  all  files  in  the  directory  C:\SOURCE  to  the  directory  C:\SOURCE\BACKUP,  type 

C>XCOPY  C:\SOURCE\*.*  C:\SOURCE\BACKUP  <Enter> 

To  copy  all  files  and  directories  on  drive  C  to  the  disk  in  drive  D,  type 

C>XCOPY  C:\*.*  D:  /S  /E  <Enter> 

Messages 

ifif  File(s)  copied 

This  informational  message  is  displayed  at  the  completion  of  an  XCOPY  command  and  in¬ 
dicates  the  total  number  of  source  files  processed. 

filename  File  not  found 

The  source  file  specified  in  the  command  line  is  invalid  or  does  not  exist. 

Xipathname  (Y/N)? 

The  /P  switch  was  specified  in  the  command  line.  XCOPY  displays  the  name  of  each  file, 
preceded  by  a  drive  (and  path,  if  one  was  specified),  and  asks  for  confirmation  before 
copying  the  file. 

Access  denied 

A  destination  file  could  not  be  overwritten  because  it  was  marked  read-only. 
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Cannot  COPY  from  a  reserved  device 

A  character  device  such  as  AUX  or  COMl  cannot  be  the  source  of  an  XCOPY  operation. 

Cannot  COPY  to  a  reserved  device 

A  character  device  such  as  PRN  cannot  be  the  destination  of  an  XCOPY  operation. 

Cannot  perform  a  cyclic  copy 

The  command  line  included  a  /S  switch  and  the  destination  directory  is  a  subdirectory  of 
the  source  directory.  A  subdirectory  cannot  be  copied  onto  itself. 

Does  name  specify  a  file  name 
or  directory  name  on  the  target 
(F  =  file,  D  =  directory)? 

The  specified  destination  directory  does  not  already  exist;  the  user  is  prompted  to  deter¬ 
mine  whether  it  should  be  created.  Respond  with  F  to  copy  the  source  file  to  a  file  named 
name\  respond  with  D  to  create  a  subdirectory  named  name  and  copy  the  source  file 
into  it. 

File  cannot  be  copied  onto  itself 

The  name  and  location  of  the  source  file  are  the  same  as  the  name  and  location  of  the  des¬ 
tination  file. 

File  creation  error 

A  destination  file  or  directory  could  not  be  created.  The  destination  disk  may  be  full. 

Incorrect  DOS  version 

The  version  of  XCOPY  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insufficient  disk  space 

The  disk  does  not  contain  enough  available  space  to  perform  the  specified  XCOPY 
operation. 

Insufficient  memory 

The  available  system  memory  is  insufficient  to  perform  the  XCOPY  operation. 

Invalid  date 

The  command  included  a  /D  switch  and  the  date  was  not  formatted  properly. 

Invalid  drive  specification 

The  source  or  destination  drive  specified  in  the  command  line  is  not  valid  or  does  not  ex¬ 
ist  in  the  system. 

Invalid  number  of  parameters 

The  command  line  contained  too  many  or  too  few  filenames  or  other  parameters. 

Invalid  parameter 

A  switch  supplied  in  the  command  line  is  not  valid. 

Invalid  patb 

A  directory  specified  in  the  command  line  is  invalid  or  does  not  exist. 
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Lock  Violation 

XCOPY  attempted  to  access  a  file  in  use  by  another  program.  Respond  with  A  to  the  error- 
message  prompt  and  try  XCOPY  later  or  wait  for  a  few  minutes  and  respond  with  R 

Path  not  found 

One  of  the  pathnames  specified  in  the  command  line  is  invalid  or  does  not  exist. 

Path  too  long 

The  path  element  of  the  source  or  destination  parameter  was  longer  than  63  characters. 

Press  any  key  to  begin  copying  file(s) 

The  /  W  switch  was  specified  in  the  command  line  and  XCOPY  waits  for  the  user  to  press  a 
key  before  beginning  the  copy  process. 

Reading  source  file(s) .. . 

This  informational  message  is  displayed  during  the  XCOPY  operation. 

Sharing  violation 

XCOPY  attempted  to  access  a  file  in  use  by  another  program.  Respond  with  A  to  the  error- 
message  prompt  and  try  XCOPY  later  or  wait  a  few  minutes  and  respond  with  R 

Too  many  open  files 

XCOPY  failed  due  to  a  lack  of  available  system  file  handles.  Increase  the  size  of  the  FILES 
command  in  the  CONFIG.SYS  file,  restart  the  system,  and  attempt  the  XCOPY  command 
again. 

Unable  to  create  directory 

A  destination  directory  cannot  have  the  same  name  as  an  existing  file  in  the  prospective 
parent  directory. 
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Introduction 


This  section  of  The  MS-DOS  Encyclopedia  describes  the  Microsoft  utilities,  documentation 
aids,  and  debuggers  that  can  be  used  with  the  Microsoft  C,  FORTRAN,  Pascal,  and  BASIC 
compilers  and  with  the  Microsoft  Macro  Assembler  (MASM).  Included  are  operating  in¬ 
structions  for  MASM,  the  Macro  Assembler;  LIB,  the  Library  Manager;  LINK,  the  Microsoft 
Object  Linker;  the  DEBUG,  SYMDEB,  and  CodeView  program  debuggers;  MAKE,  which 
automates  maintenance  of  programs;  CREF,  which  produces  a  cross-reference  listing  of 
symbols;  and  EXE2BIN,  EXEMOD,  and  EXEPACK,  which  modify  executable  files. 

Entries  (except  for  the  program  debuggers)  are  arranged  alphabetically  by  the  name  of  the 
programming  utility.  The  three  Microsoft  debuggers  are  listed  at  the  end  of  the  section  in 
the  following  order:  DEBUG,  SYMDEB,  CodeView.  Individual  DEBUG  and  SYMDEB  com¬ 
mands  appear  alphabetically  under  the  headings  DEBUG  and  SYMDEB. 

Each  utility  entry  includes 

•  Utility  name 

•  Utility  purpose 

•  Prototype  command  line  and  summary  of  options 

•  Detailed  description  of  utility 

•  One  or  more  examples  of  utility  use 

•  Return  codes  (where  applicable) 

•  Error  messages  and  warnings  (where  applicable) 

The  experienced  user  can  find  information  with  a  quick  glance  at  the  first  part  of  a  utility 
entry;  a  less  experienced  user  can  refer  to  the  detailed  explanation  and  examples  in  a  more 
leisurely  fashion.  The  next  two  pages  contain  an  example  of  a  typical  entry  from  the 
Programming  Utilities  section,  with  explanations  of  each  component. 
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HEADING - 

The  utility  name. 

PURPOSE  - 

An  abstract  of  utility 
purpose  and  usage  plus 
a  statement  of  which 
Microsoft  products  the 
utility  is  supplied  with 
and  the  utility  version 
described  in  the  entry. 

SYNTAX - 

A  prototype  command 
line,  with  variable  names 
in  italic  and  optional 
parameters  in  square 
brackets.  The  various 
elements  of  the  com¬ 
mand  line  should  be  en¬ 
tered  in  the  order  shown. 
Any  punctuation  must 
be  used  exactly 
as  shown;  in  commands 
that  use  commas  as  sep¬ 
arators,  the  comma 
usually  must  be  included 
as  a  placeholder  even  if 
the  parameter  is  omit¬ 
ted.  Except  where  noted, 
commands,  parameters, 
and  switches  can  be  en¬ 
tered  in  either  uppercase 
or  lowercase.  Utility 
names  can  be  preceded 
by  a  drive  and/or  path. 


EXEPACK 

Compress  .EXE  File 


*  Purpose 

Compresses  an  executable  .EXE  program  file  so  that  it  requires  less  space  on  the  disk. 

The  EXEPACK  utility  is  supplied  with  the  Microsoft  Macro  Assembler  (MASM),  C  Compiler, 
FORTRAN  Compiler,  and  Pascal  Compiler.  This  documentation  describes  EXEPACK 
version  4.04. 

—  Syntax 

EXEPACK  exe_fitepacked_file 


exe^file 

packed^/ile 

Description 


is  the  name  cK^e  executable  .EXE  program  file  to  be  compressed, 
is  the  name4N  the  compressed  program  file. 


The  EXEPACK  utility  compresses  an  executable  .EXE  program  by  packing ^quences  of 
identical  bytes  and  optimizing  the  relocation  table.  The  EXEPACK  utilitW^ot  compatible 
with  versions  of  MS-DOS  earlier  than  2.0. 

The  exe^/ile  parameter  specifies  the  name  of  the  program  file  MdSuced  by  the  Microsoft 
Object  Linker  (LINK)  and  must  contain  the  extension  .EXE.  T^packed^file  parameter 
specifies  the  name  and  extension  of  the  resulting  compress^ofile.  EXEPACK  has  no 
default  extensions. 

The  name  for  packed^file  must  be  different  from  t)y^exe^file  filename.  Although  it  is 
possible  to  fool  EXEPACK  into  creating  a  packed  (Me  with  the  same  name  by  specifying  a 
different  but  equivalent  pathname  for  the  outmi^ile,  the  resulting  packed  file  will  proba¬ 
bly  be  damage.  If  the  packed  file  is  to  repl^ the  original  .EXE  file,  a  different  name 
should  be  specifted  for  the  packed  file;  thdn  the  input  file  should  be  deleted  and  the 
packed  file  renamed  with  the  name  of«me  original  file. 

When  EXEPACK  is  used  to  comraifo  an  executable  overlay  file  or  a  program  that  calls 
overlays,  the  packed  file  shouk^  renamed  with  its  original  name  before  use  to  avoid 
interruption  ^  the  overlaj^pnager  prompt. 


The  effects  of  EXEPA( 
cessed  with  EXEPACK^to  oc< 
also  load  for  exea/ion  mon 
tually  become^il^er  after 
EXEPACK ^^Id  be  discard] 
under  OEtfUG,  SYMDEB,  or 
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:nd  on  program  characteristics.  Most  programs  can  be  pro- 
■X  upy  significantly  less  disk  space.  Programs  thus  compressed 
re  quickly.  Occasionally  programs  (particularly  small  ones)  ac- 
pr  xressing  with  EXEPACK;  in  such  cases  the  file  produced  by 
I  d.  Microsoft  Windows  programs  or  programs  to  be  debugged 
CodeView  should  not  be  compressed  with  EXEPACK. 


BELOW  WHERE 
A  brief  explanation 
of  each  command 
parameter  and  switch. 
Filenames  are  always 
listed  first,  followed  by 
the  switches  in  alpha¬ 
betic  order.  Any  special 
position  required  for  a 
filename  or  switch  is 
shown  in  the  syntax 
line  and  noted  in  the 
explanation. 


DESCRIPTION 
A  detailed  description 
of  the  utility,  including 
a  full  explanation  of 
default  values,  possible 
interactions  of  command 
parameters  and  options, 
useful  background  infor¬ 
mation,  and  any  applic¬ 
able  warnings. 
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EXEPACK 


Using  EXEPACK  on  a  previoufi] 
/EXEPACK  switch  while  linki(| 


Note:  When  using  the  EXEMd 
or  the  /EXEPACK  linker  switc|i, 
EXEPACK  utility  to  ensure  coi 

Return  Codes 


ly  linked  program  is  equivalent  to  specifying  LINK'S 
|tg  that  program. 

•D  utility  with  packed  .EXE  files  created  with  EXEPACK 
i,  use  the  EXEMOD  version  shipped  with  LINK  or  with  the 
itjipatibiliiy. 


Las  successful. 


Example 


To  compress  the  file  BUILD.EXE  into  ^  named  BUILDX.EXE,  type 

OEXEPACK  BUILD.EXE  BUILDX.EXE  ^ghCer> 


0  No  error;  the  EXEPACK  o J^tion 

1  An  error  was  encounter^^miat  terminated  execution  of  the  EXEPACK  utility. 


fatal  error  UllOO:  out  of  space  on  output  file  y 

The  destination  disk  has  insufficient  space  for  the  output  file,  or  the  root  dirttf^  is  full. 

fatal  error  UllOl:  JUename :  file  not  found 

The  .EXE  file  specified  in  the  command  line  cannot  be  found. 

fatal  error  U1102:.^Uefuime :  permission  denied 

A  file  with  the  same  name  as  the  specified  output  file  already ^^s  and  is  read-only. 

fatal  error  U1103:  cannot  pack  file  onto  Itself 

The  file  cannot  be  compressed  because  the  name  specjfi^  for  th^  packed  file  is  the  same 
as  the  name  of  the  source  .EXE  file. 


fatal  error  U1104:  usage  t 
The  command  line  contained  a  syntax  error,  a 


t  exepack  <lnfile:yi 


^the  output  filename  was  not  specified. 


fatal  error  UU05t  invalid  .E 

The  file  is  not  an  executable  file  or  h 

fatal  error  UU06:  c 
The  file  cannot  be  compre 
allocation  value  are  both  z 


dheader 

n  invalid  file  header, 
e  load-high  program 

e  the  minimum  allocation  value  and  the  maximum 
3  PROGRAMMING  UTILITIES;  exemod. 


fatal  error  UUOTi  c 
The  file  specified  h 


aot  pack  already-packed  file 


invalid  .EXE  file;  actual  length  less  than  reported 
[icated  in  the  .EXE  file  header  does  not  match  the  size  recorded  in  the  disk 


already  been  packed  with  EXEPACK. 

y 

fatal  errori 

The  file  size 
directory. 

or  U1109:  out  of  memory 

Thp^XEPACK  utility  did  not  have  enough  memory  to  operate. 
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RETURN  CODES 
Exit  codes  returned  by 
the  utility  (if  any)  that 
can  be  tested  in  a  batch 
file  or  by  another 
program. 

EXAMPLES 
One  or  more  examples 
of  the  utility  at  work, 
including  examples  of 
the  resulting  output 
where  appropriate.  User 
entry  appears  in  color; 
do  not  type  the  prompt, 
which  appears  in  black. 
Press  the  Enter  key 
(labeled  Return  on  some 
keyboards)  as  directed 
at  the  end  of  each  com¬ 
mand  line. 

MESSAGES 
An  alphabetic  list  of 
messages  that  may  be 
displayed  when  the 
utility  is  used.  Following 
each  message  is  a  brief 
explanation  of  the  con¬ 
dition  that  produces  the 
message  and,  where 
appropriate,  any  action 
that  should  be  taken. 
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CREF 

Generate  Cross-Reference  Listing 


Purpose 

Produces  a  cross-reference  listing  of  all  symbols  in  an  assembly-language  program.  The 
CREF  utility  is  supplied  with  the  Microsoft  Macro  Assembler  (MASM).  This  documentation 
describes  CREF  version  4.0. 

Syntax 

CREF 

or 

CREF  crf_file[{\ 
or 

CREF  crfj^ile.ref^file 
where: 

crf^file  is  the  input  file  previously  produced  by  MASM  (default  extension  =  .CRF). 
ref_file  is  the  output  ASCII  text  file  to  be  created  (default  extension  =  .REF). 

Description 

The  CREF  utility  processes  a  file  produced  by  MASM  and  generates  an  ASCII  cross- 
reference  listing  in  a  file  on  disk  or  directly  on  a  character  device  (such  as  a  printer).  The 
output  file  contains  an  alphabetic  list  of  the  symbols  in  the  assembled  program,  including 
the  line  number  of  each  reference  to  the  symbol  and  the  total  number  of  symbols  in  the 
program.  A  pound  sign  (#)  follows  the  line  number  of  the  reference  that  defines  the 
symbol. 

The  crf_file  has  the  default  extension  .CRF.  It  is  produced  by  providing  MASM  with  a  file¬ 
name  other  than  NUL  in  the  cross-reference  position  in  the  command  line,  by  responding 
to  the  Cross-reference:  prompt,  or  by  including  the  /C  switch  in  the  MASM  command  line 
or  at  any  MASM  prompt.  An  assembly  source  listing  file  (.LST)  must  also  be  requested  in 
the  MASM  command  line  or  in  response  to  the  MASM  prompts  in  order  to  generate  a  valid 
.CRF  file. 

If  a  semicolon  follows  the  crf_file  parameter  in  the  CREF  command,  the  resulting  ref_file 
containing  the  cross-reference  listing  is  given  the  same  drive  and  pathname  as  crf^file, 
with  a  .REF  extension.  If  the  optional  ref.file  parameter  is  present,  it  can  consist  of  any 
pathname  with  an  optional  extension  (default  is  .REF).  The  cross-reference  listing  can  be 
sent  directly  to  a  character  device,  rather  than  to  a  file,  by  specifying  a  valid  character 
device  name  (such  as  PRN)  in  the  ref_file  position. 
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If  the  CREF  utility  is  run  without  any  parameters  or  with  some  parameters  missing,  the 
CREF  utility  prompts  the  operator  for  the  necessary  information. 

Return  Codes 

0  No  error;  the  CREF  operation  was  successful. 

1  An  error  was  encountered  that  terminated  execution  of  the  CREF  utility. 

Examples 

To  process  the  file  MENUMGR.CRF  (created  during  assembly  of  MENUMGR.ASM)  into  the 
cross-reference  file  MENUMGR.REF,  type 

OCREF  MENUMGR;  <Enter> 

To  process  the  file  MENUMGR. CRF  and  assign  the  name  MENU.REF  to  the  resulting  cross- 
reference  file,  type 

OCREF  MENUMGR,  MENU  <Enter> 

To  process  the  file  MENUMGR. CRF  and  send  the  cross-reference  listing  directly  to  the 
printer,  type 

OCREF  MENUMGR,  PRN  <Enter> 

To  run  the  CREF  program  in  interactive  mode,  type 

OCREF  <Enter> 

The  following  is  an  example  of  an  interactive  CREF  session: 

OCREF  <Enter> 

Microsoft  (R)  Cross  Reference  Utility  Version  4.00 

Copyright  (C)  Microsoft  Corp  1981,  1983,  1984,  1985.  All  rights  reserved. 

Cross-reference  [.CRF]:  MENUMGR  <Enter> 

Listing  [MENUMGR.REF]:  <Enter> 

9  Symbols 

O 

The  following  sequence  of  commands  produces  the  cross-reference  listing  HELLO.REF 
from  the  assembly-language  source  file  HELLO.ASM: 

OMASM  HELLO,  HELLO,  HELLO,  HELLO  <Enter> 

OCREF  HELLO;  <Enter> 
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Contents  of  the  file  HELLO.  ASM: 


name  hello 

page  55,132 

title  HELLO. ASM  -  print  Hello  on  terminal 


;  HELLO 

.COM  utility  to  demonstrate  CREF  listing 

cr 

equ 

Odh 

; ASCI I  carriage  return 

If 

equ 

Oah 

/ASCII  linefeed 

cseg 

segment 

para  public 

"CODE" 

org 

lOOh 

assume 

cs : cseg, ds : cseg, es : cseg, ss : cseg 

print 

proc 

near 

mov 

dx, offset  message 

mov 

ah,  9 

/print  the  string  "Hello" 

int 

21h 

mov 

ax, 4c00h 

/exit  to  MS-DOS 

int 

21h 

/with  "return  code"  of  zero 

print 

endp 

message 

db 

cr, If, 'Hello 

!  ’,cr,lf, •$• 

cseg 

ends 

end 

print 

Contents  of  the  file  HELLO.REF: 


Microsoft  Cross-Reference  Version  4.00  Mon  Sep  07  23:31:21  1987 

HELLO. ASM  -  print  Hello  on  terminal 


Symbol  Cross-Reference 

(#  is 

definition) 

Cref-1 

CODE . . 

.  .  10 

CR . 

.  .  7 

7# 

24 

25 

CSEG . . 

.  .  10 

10# 

14 

14 

14 

14  27 

LF . . 

.  .  8 

8# 

24 

25 

MESSAGE . 

17 

24 

24# 

PRINT . 

16 

16# 

29 

6  Symbols 
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Messages 

can’t  open  cross-reference  file  for  reading 

The  pathname  or  drive  specified  for  the  input  .CRF  file  is  invalid  or  does  not  exist. 

can’t  open  listing  file  for  writing 

A  write  error  has  halted  the  creation  of  the  .REF  listing  file.  This  indicates  that  the  disk  is 
full  or  write-protected,  that  the  specified  output  file  is  read-only,  or  that  the  specified 
device  is  not  available. 

cref  has  no  switches 

A  switch  was  specified  in  the  command  line;  CREF  has  no  optional  switches. 

DOS  2.0  or  later  required 

CREF  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

extra  file  name  ignored 

More  than  two  filenames  were  specified  in  the  command  line.  The  CREF  utility  generates 
the  cross-reference  listing  using  the  first  two  filenames  specified. 

line  invalid,  start  again 

No  .CRF  file  was  specified  in  the  command  line  or  at  the  prompt.  Specify  a  valid  .CRF  file 
at  the  prompt  following  this  message. 

out  of  heap  space 

Memory  is  insufficient  to  process  the  .CRF  file.  Remove  memory-resident  programs  and 
shells  or  add  more  memory. 

premature  eof 

The  input  file  specified  is  damaged  or  is  not  a  valid  .CRF  file. 

read  error  on  stdin 

A  Control-Z  was  received  from  the  keyboard  or  a  redirected  file  and  has  halted  CREF. 
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EXE2BIN 

Convert  .EXE  File  to  Binary-Image  File 


Purpose 

Converts  an  executable  file  in  the  .EXE  format  to  a  memory-image  file  in  binary  format. 
The  EXE2BIN  utility  is  supplied  with  the  MS-DOS  distribution  disks. 

Syntax 

EXE2BIN  lbin_file] 

where: 

exe^ file  is  the  .EXE-format  file  to  be  converted  (default  extension  =  .EXE). 

bin^file  is  the  name  to  be  given  to  the  converted  file  (default  extension  =  .BIN). 

Description 

The  .EXE  executable  program  files  produced  by  the  Microsoft  Object  Linker  (LINK) 
contain  a  special  header  and  a  relocation  table  as  well  as  the  program  code  and  data.  The 
EXE2BIN  utility  can  be  used  to  convert  a  .EXE  file  to  a  .COM  executable  file,  which  is  an 
absolute  memory  image  of  the  program  to  be  executed  and  does  not  contain  a  special 
header  or  relocation  table.  The  EXE2BIN  utility  can  also  be  used  to  convert  .EXE  files  with 
an  origin  of  zero  (such  as  installable  MS-DOS  device  drivers)  to  pure  memory-image  files. 
Files  in  memory-image  format  (a  common  format  for  device  drivers  and  for  programs  to  be 
placed  in  ROM  for  execution)  usually  have  a  .BIN  or  .SYS  extension. 

To  convert  a  .EXE  program  to  a  binary-image  file,  the  following  are  required: 

•  The  program  must  be  a  valid  .EXE  file  produced  by  LINK. 

•  The  program  can  contain  only  one  segment  and  cannot  contain  a  declared  stack 
segment. 

•  The  program  code  and  data  portion  of  the  .EXE  file  must  be  less  than  64  KB. 

To  convert  a  .EXE  program  to  an  executable  .COM  file,  the  following  are  required: 

•  The  origin  of  the  program  must  be  OlOOH,  which  must  also  be  specified  as  the  entry 
point. 

•  The  program  code  and  data  portion  of  the  .EXE  file  must  be  less  than  65227  bytes 
(64  KB  minus  256  bytes  used  by  the  program  segment  prefix  minus  2  bytes  initially 
placed  on  the  stack). 

•  The  program  must  not  include  any  FAR  references. 
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Note:  Many  compilers  cannot  create  programs  that  can  be  converted  to  .COM  files.  Check 
the  compiler  documentation  for  specific  information  concerning  executable  .COM  files. 

The  exe^file  parameter  in  the  command  line  can  have  any  filename  and  can  include  a 
drive  and  path;  the  default  extension  is  .EXE.  The  optional  bin_file  parameter  can  also 
contain  any  filename  and  a  drive  and  path;  the  default  extension  is  .BIN.  If  no  path  is  spec¬ 
ified  with  the  bin^file  parameter,  the  output  file  is  given  the  same  drive  and  path  as  the 
exe^file.  If  no  bin__file  parameter  is  supplied,  the  output  file  is  given  the  same  name  as 
the  exe^file,  with  the  extension  .BIN. 

If  the  program  in  the  .EXE  file  requires  segment  fixups  (that  is,  if  the  program  contains 
instructions  requiring  segment  relocation,  which  would  ordinarily  be  done  by  the  MS-DOS 
loader  using  the  .EXE  file’s  relocation  table),  EXE2BIN  prompts  for  a  base  segment  ad¬ 
dress.  When  segment  fixups  are  necessary,  the  resulting  program  is  not  relocatable  and 
must  be  loaded  at  the  given  location  to  be  executed;  the  MS-DOS  loader  cannot  load  the 
program. 

Examples 

To  convert  the  file  HELLO.EXE  to  the  file  HELLO.BIN,  type 

OEXE2BIN  HELLO  <Enter> 

To  convert  the  file  CLEAN.EXE,  which  has  an  origin  of  OlOOH  and  meets  the  requirements 
for  an  executable  .COM  file,  to  the  file  CLEAN.COM,  type 

OEXE2BIN  CLEAN.EXE  CLEAN.COM  <Enter> 

To  convert  the  file  ASYNCH.EXE,  produced  by  assembling  and  linking  the  device-driver 
source  file  ASYNCH.ASM,  to  the  installable  device-driver  file  ASYNCH.SYS,  type 

OEXE2BIN  ASYNCH.EXE  ASYNCH.SYS  <Enter> 

Messages 

File  cannot  be  converted 

The  program  to  be  converted  has  one  of  the  following  problems:  The  program  has  an 
origin  of  OlOOH  but  a  different  entry  point;  the  program  requires  segment  fixups;  the  pro¬ 
gram  code  and  data  are  larger  than  64  KB;  the  program  has  more  than  one  declared  seg¬ 
ment;  or  the  file  is  not  a  valid  .EXE-format  file. 

File  creation  error 

EXE2BIN  cannot  create  the  output  file  because  a  read-only  file  with  the  same  name 
already  exists,  because  the  specified  directory  is  full,  or  because  the  specified  disk  is  full, 
write-protected,  or  unreadable. 

File  not  found 

The  file  does  not  exist  or  the  incorrect  path  was  given. 
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Fixups  needed  -  base  segment  (hex): 

The  .EXE-format  file  contains  segment  references  that  would  ordinarily  be  relocated  by 
the  .EXE  file  loader.  Specify  the  absolute  segment  address  at  which  the  converted  module 
will  be  executed. 

Incorrect  DOS  version 

The  version  of  EXE2BIN  is  not  compatible  with  the  version  of  MS-DOS  that  is  running. 

Insufficient  disk  space 

The  destination  disk  has  insufficent  space  to  create  the  memory-image  output  file. 

Insufficient  memory 

Not  enough  memory  is  available  to  run  EXE2BIN. 

WARNING  -  Read  error  in  EXE  f Ue. 

Amount  read  less  than  size  in  header. 

The  file  size  given  in  the  .EXE  header  is  inconsistent  with  the  actual  size  of  the  file. 
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EXEMOD 

Modify  .EXE  File  Header 

Purpose 

Allows  inspection  or  modification  of  the  fields  in  a  .EXE  file  header.  The  EXEMOD  utility 
is  supplied  with  the  Microsoft  Macro  Assembler  (MASM),  C  Compiler,  FORTRAN  Compiler, 
and  Pascal  Compiler.  This  documentation  describes  EXEMOD  version  4.02. 

Syntax 

EXEMOD  exe^fHeUH] 
or 

EXEMOD  exe^fileUSTKCY.  n]  [/MAX  n]  [/MIN  n] 
where: 

exe_file  is  the  name  of  an  executable  program  in  .EXE  format  (the  extension  .EXE 
is  assumed). 

/H  displays  the  values  in  the  file’s  header. 

/STACK  n  modifies  the  size  of  the  program’s  stack  segment  to  n  (hexadecimal) 
bytes. 

/MAX  n  sets  the  maximum  memory  allocation  for  the  program  to  n  (hexadecimal) 

paragraphs. 

/MIN  n  sets  the  minimum  memory  allocation  for  the  program  to  n  (hexadecimal) 

paragraphs. 

Note:  Switches  can  be  either  uppercase  or  lowercase  and  can  be  preceded  by  a  dash  (-) 
instead  of  a  forward  slash  (/). 

Description 

Programs  that  are  executable  under  MS-DOS  can  be  in  one  of  two  file  formats:  .COM, 
which  is  an  absolute  image  of  the  file  to  be  executed  and  limits  the  program  size  to  65227 
bytes  (64  KB  minus  256  bytes  used  by  the  program  segment  prefix  minus  2  bytes  initially 
placed  on  the  stack);  or  .EXE,  which  allows  a  program  of  any  size  to  be  loaded  and  has  a 
special  header  containing  information  about  the  program’s  entry  point,  stack  size,  and 
memory  requirements,  plus  a  relocation  table. 

The  EXEMOD  utility  can  be  used  to  display  or  modify  those  fields  of  a  .EXE  program 
header  that  control  the  size  of  the  stack  segment  and  the  amount  of  memory  allocated  to 
the  program  when  MS-DOS  loads  the  program  into  the  transient  program  area  for 
execution. 

The  /STACKw  switch  controls  the  number  of  bytes  in  the  program’s  STACK  segment  by 
setting  the  initial  SP  to  the  hexadecimal  value  specified.  The  minimum  paragraph  alloca¬ 
tion  value  is  adjusted  if  necessary.  The  EXEMOD  /STACKw  switch  should  be  used  only 
with  programs  compiled  by  Microsoft  C  version  3.0  or  later,  Microsoft  Pascal  version  3.3 
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or  later,  or  Microsoft  FORTRAN  version  3.0  or  later.  Use  of  the  /STACKw  switch  with  a  pro¬ 
gram  developed  with  another  compiler  can  cause  the  program  to  fail  or  cause  EXEMOD  to 
return  an  error  message. 

The  /MAXw  switch  specifies  the  maximum  number  of  additional  paragraphs  of  memory 
to  allocate  for  use  by  the  program.  The  /MINn  switch  specifies  the  minimum  number  of 
paragraphs  of  memory,  in  addition  to  the  size  of  the  program  itself  and  its  stack  and  data 
segments,  that  are  required  for  the  program  to  execute.  If  enough  memory  exists  to  satisfy 
the  minimum  additional  paragraphs  requested  but  not  enough  exists  to  satisfy  the  max¬ 
imum,  MS-DOS  allocates  all  available  memory  to  the  program. 

To  display  the  current  memory  allocation  and  stack  size  values  from  a  .EXE  file’s  header, 
the  /H  switch  can  be  used  or  the  file’s  name  can  be  entered  as  the  only  parameter  in  the 
command  line. 

When  EXEMOD  is  used  on  a  previously  packed  .EXE  file  (a  file  that  was  processed  by 
EXEPACK  or  linked  with  the  /EXEPACK  switch),  the  values  set  or  displayed  in  the  file’s 
header  are  the  values  that  will  apply  after  the  file  is  expanded  at  load  time.  EXEMOD  dis¬ 
plays  a  message  advising  the  user  that  the  file  being  modified  was  previously  packed. 

The  EXEMOD  switches  /MAXw  and  /STACKw  correspond  to  the  Microsoft  Object  Linker’s 
/CPARMAXALLOC:w  and /STACK:  w  switches,  respectively.  See  PROGRAMMING 
UTILITIES:  link. 

Return  Codes 

0  No  error;  EXEMOD  operation  was  successful. 

1  An  error  was  encountered  that  terminated  execution  of  the  EXEMOD  program. 

Examples 

To  display  the  values  in  the  file  header  of  the  DUMP.EXE  program,  type 

C> EXEMOD  DUMP.EXE  <Enter> 

or 

C> EXEMOD  DUMP.EXE  /H  <Enter> 

The  EXEMOD  utility  displays  the  following: 

Microsoft  (R)  EXE  File  Header  Utility  Version  4.02 


Copyright  (C)  Microsoft  Corp 

1985.  All  rights 

reserved. 

DUMP . EXE 

(hex) 

(dec) 

.EXE  size  (bytes) 

580 

1408 

Minimum  load  size  (bytes) 

383 

899 

Overlay  number 

0 

0 

Initial  CS:IP 

Initial  SS:SP 

0000:0000 

0034:0040 

64 

Minimum  allocation  (para) 

5 

5 

Maximum  allocation  (para) 

FFFF 

65535 

Header  size  (para) 

20 

32 

Relocation  table  offset 

20 

32 

Relocation  entries 

1 

1 
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To  change  the  size  of  the  STACK  segment  for  the  DUMP.EXE  program  to  400H  (1024) 
bytes,  type 

C> EXEMOD  DUMP.EXE  /STACK  400  <Enter> 

EXEMOD  displays  the  message 

EXEMOD  :  warning  U4051 :  minimum  allocation  less  than  stack;  correcting  minimum 

Messages 

error  U1050:  usage :  exemod  file  [-/h]  [-/stack  n]  [-/max  n]  [-/min  n] 

An  error  was  detected  in  the  EXEMOD  command  line. 

error  U1051:  invalid  .EXE  file :  bad  header 

The  file  is  not  an  executable  file  or  has  an  invalid  file  header. 

error  U1052:  invalid  .EXE  file :  actual  length  less  than  reported 

The  file  size  indicated  in  the  .EXE  file  header  does  not  match  the  size  recorded  in  the  disk 
directory. 

error  U1053:  cannot  change  load-high  program 

The  header  of  the  file  cannot  be  modified  because  the  minimum  allocation  value  and  the 
maximum  allocation  value  are  both  zero. 

error  U1054:  file  not  .EXE 

The  file  specified  does  not  have  a  .EXE  extension. 

error  U1055:  filename :  cannot  find  file 

The  .EXE  file  specified  in  the  command  line  cannot  be  found. 

error  UIO56:  filename  :  permission  denied 

The  .EXE  file  specified  in  the  command  line  is  read-only. 

warning  U4050:  packed  file 

The  specified  file  is  a  packed  file;  that  is,  it  was  previously  processed  with  the  EXEPACK 
utility  or  was  linked  with  the  /EXEPACK  switch.  This  is  an  informational  message  only; 
EXEMOD  still  modifies  the  file.  The  header  values  displayed  are  the  values  that  will  apply 
after  the  packed  value  is  expanded  at  load  time. 

warning  U4031:  minimum  allocation  less  than  stack;  correcting  minimum 

The  minimum  allocation  value  is  not  large  enough  to  accommodate  the  stack;  the 
minimum  allocation  value  is  adjusted.  This  is  an  informational  message  only. 

warning  U4052:  minimum  allocation  greater  than  maximum;  correcting 
maximum 

If  the  minimum  allocation  value  is  greater  than  the  maximum  allocation  value,  the  maxi¬ 
mum  value  is  adjusted.  This  is  an  informational  message  only. 
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EXEPACK 

Compress  .EXE  File 


Purpose 

Compresses  an  executable  .EXE  program  file  so  that  it  requires  less  space  on  the  disk. 

The  EXEPACK  utility  is  supplied  with  the  Microsoft  Macro  Assembler  (MASM),  C  Compiler, 
FORTRAN  Compiler,  and  Pascal  Compiler.  This  documentation  describes  EXEPACK 
version  4.04. 

Syntax 

EXEPACK  exe^ file  packed_file 
where: 

exe^  file  is  the  name  of  the  executable  .EXE  program  file  to  be  compressed. 

packed^file  is  the  name  of  the  compressed  program  file. 

Description 

The  EXEPACK  utility  compresses  an  executable  .EXE  program  by  packing  sequences  of 
identical  bytes  and  optimizing  the  relocation  table.  The  EXEPACK  utility  is  not  compatible 
with  versions  of  MS-DOS  earlier  than  2.0. 

The  exe^file  parameter  specifies  the  name  of  the  program  file^roduced  by  the  Microsoft 
Object  Linker  (LINK)  and  must  contain  the  extension  .EXE.  The  packed^  file  parameter 
specifies  the  name  and  extension  of  the  resulting  compressed  file.  EXEPACK  has  no 
default  extensions. 

The  name  for packed^file  must  be  different  from  the  exe^ file  filename.  Although  it  is 
possible  to  fool  EXEPACK  into  creating  a  packed  file  with  the  same  name  by  specifying  a 
different  but  equivalent  pathname  for  the  output  file,  the  resulting  packed  file  will  proba¬ 
bly  be  damaged.  If  the  packed  file  is  to  replace  the  original  .EXE  file,  a  different  name 
should  be  specified  for  the  packed  file;  then  the  input  file  should  be  deleted  and  the 
packed  file  renamed  with  the  name  of  the  original  file. 

When  EXEPACK  is  used  to  compress  an  executable  overlay  file  or  a  program  that  calls 
overlays,  the  packed  file  should  be  renamed  with  its  original  name  before  use  to  avoid 
interruption  by  the  overlay-manager  prompt. 

The  effects  of  EXEPACK  depend  on  program  characteristics.  Most  programs  can  be  pro¬ 
cessed  with  EXEPACK  to  occupy  significantly  less  disk  space.  Programs  thus  compressed 
also  load  for  execution  more  quickly.  Occasionally  programs  (particularly  small  ones)  ac¬ 
tually  become  larger  after  processing  with  EXEPACK;  in  such  cases  the  file  produced  by 
EXEPACK  should  be  discarded.  Microsoft  Windows  programs  or  programs  to  be  debugged 
under  DEBUG,  SYMDEB,  or  CodeView  should  not  be  compressed  with  EXEPACK. 
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Using  EXEPACK  on  a  previously  linked  program  is  equivalent  to  specifying  LINK’S 
/EXEPACK  switch  while  linking  that  program. 

Note:  When  using  the  EXEMOD  utility  with  packed  .EXE  files  created  with  EXEPACK 
or  the  /EXEPACK  linker  switch,  use  the  EXEMOD  version  shipped  with  LINK  or  with  the 
EXEPACK  utility  to  ensure  compatibility. 

Return  Codes 

0  No  error;  the  EXEPACK  operation  was  successful. 

1  An  error  was  encountered  that  terminated  execution  of  the  EXEPACK  utility. 

Example 

To  compress  the  file  BUILD.EXE  into  a  file  named  BUILDX.EXE,  type 

C> EXEPACK  BUILD.EXE  BUILDX.EXE  <Enter> 

Messages 

fatal  error  UllOO:  out  of  space  on  output  file 

The  destination  disk  has  insufficient  space  for  the  output  file,  or  the  root  directory  is  full. 

fatal  error  UllOl:  filename :  file  not  found 

The  .EXE  file  specified  in  the  command  line  cannot  be  found. 

fatal  error  U1102:  filename :  permission  denied 

A  file  with  the  same  name  as  the  specified  output  file  already  exists  and  is  read-only. 

fatal  error  U1103^annot  pack  file  onto  itself 

The  file  cannot  be  compressed  because  the  name  specified  for  the  packed  file  is  the  same 
as  the  name  of  the  source  .EXE  file. 

fatal  error  U1104:  usage :  exepack  <inf ile>  <outfile> 

The  command  line  contained  a  syntax  error,  or  the  output  filename  was  not  specified. 

fatal  error  U1105:  invalid  .EXE  file;  bad  header 

The  file  is  not  an  executable  file  or  has  an  invalid  file  header. 

fatal  error  UIIO6:  cannot  change  load-high  program 

The  file  cannot  be  compressed  because  the  minimum  allocation  value  and  the  maximum 
allocation  value  are  both  zero.  See  also  PROGRAMMING  UTILITIES:  exemod. 

fatal  error  U1107:  cannot  pack  already-packed  file 

The  file  specified  has  already  been  packed  with  EXEPACK. 

fatal  error  U1108:  invalid  .EXE  file;  actual  length  less  than  reported 

The  file  size  indicated  in  the  .EXE  file  header  does  not  match  the  size  recorded  in  the  disk 
directory. 

fatal  error  U1109:  out  of  memory 

The  EXEPACK  utility  did  not  have  enough  memory  to  operate. 


978  The  MS-DOS  Encyclopedia 


EXEPACK 


fatal  error  UlllO:  error  reading  relocation  table 

The  file  cannot  be  compressed  because  the  relocation  table  cannot  be  found  or  is  invalid. 

fatal  error  Ullll:  file  not  suitable  for  packing 

The  file  could  not  be  packed  because  the  packed  load  image  of  the  specified  file  was 
larger  than  the  unpacked  load  image. 

fatal  error  U1112:  filename :  unknown  error 

An  unknown  system  error  occurred  while  the  specified  file  was  being  processed. 

warning  U4100:  omitting  debug  data  from  output  file 

EXEPACK  has  stripped  all  symbolic  debug  information  from  the  output  file. 
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LIB 

Library  Manager 

Purpose 

Creates  or  modifies  an  object  module  library  file.  The  LIB  utility  is  supplied  with  the 
Microsoft  Macro  Assembler  (MASM),  C  Compiler,  FORTRAN  Compiler,  and  Pascal  Com¬ 
piler.  This  documentation  describes  LIB  version  3.06. 

Syntax 

LIB 

or 

LIB  library_file[/VhGESlZE\n]  loperation]lXlist_file]Unew_library^file^^^  [;] 
or 

LIB  @response^file 
where: 

library^  file  is  the  name  of  the  object  module  library  file  to  be  created  or  modi¬ 

fied  (default  extension  =  .LIB). 

/PAGESIZE:  n  is  the  page  size  of  the  library  file  and  must  immediately  follow 

library^file  if  used;  w  is  a  power  of  2  between  16  and  32768, 
inclusive  (default  =  16).  Can  be  abbreviated  /P:  w. 
operation  is  one  or  more  library  manipulations  to  be  performed.  Each 

operation  is  specified  as  a  code  followed  by  an  object  module 
name  (case  is  not  significant): 

+ name  Add  object  module  or  another  library  to  library. 

-name  Delete  object  module  from  library. 

-+  name  Replace  object  module  in  library. 

♦  name  Copy  object  module  from  library  to  object  file. 

-*name  Copy  object  module  to  object  file  and  then  delete 
object  module  from  library. 

is  the  name  of  the  file  or  character  device  to  receive  the  cross- 
reference  listing  for  the  library  file  (default  =  NUL  device), 
is  the  name  to  be  assigned  to  the  modified  object  module  library 
file.  (The  default  name  is  the  same  as  library^  file;  if  the  default  is 
used,  the  original  library^ file  is  renamed  with  the  extension 
.BAK.) 

is  the  name  of  a  text  file  containing  LIB  parameters  in  the  same 
order  in  which  they  are  supplied  if  entered  interactively.  The  name 
of  the  response  file  must  be  preceded  by  the  @  symbol. 


list^file 

new^library^ file 

response_file 
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Description 

The  Microsoft  Library  Manager  (LIB)  creates  and  modifies  library  files,  checks  existing 
library  files  for  consistency,  and  prints  listings  of  the  contents  of  library  files.  The  LIB 
utility  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

A  library  file  consists  of  relocatable  object  modules  that  are  indexed  by  their  names  and 
public  symbols.  The  Microsoft  Object  Linker  (LINK)  uses  these  files  during  the  creation  of 
an  executable  (.EXE)  program  to  resolve  external  references  to  routines  and  variables  con¬ 
tained  in  other  object  modules. 

The  library^file  parameter  specifies  the  name  of  the  object  module  library  file  to  be 
created  or  modified.  This  parameter  is  required;  if  it  is  not  included,  LIB  prompts  for  it. 

The  default  extension  for  a  library  file  is  .LIB. 

The  /PAGESIZEiw  switch  (abbreviated  /P:«)  sets  the  page  size  (in  bytes)  for  a  new  library 
file  or  changes  the  page  size  of  an  existing  library  file.  The  value  of  n  must  be  a  power  of  2 
between  16  and  32768,  inclusive.  The  default  is  16  for  a  new  library  file;  for  an  existing  li¬ 
brary  file,  the  default  is  the  current  page  size.  Because  the  index  to  a  library  file  is  con¬ 
tained  in  a  fixed  number  of  pages,  setting  a  larger  page  size  increases  the  number  of  index 
entries  (and  thus  the  number  of  object  modules)  that  a  library  file  can  contain  but  results  in 
more  wasted  disk  space  (an  average  of  half  a  library  page  per  object  module). 

The  operation  parameter  specifies  one  or  more  relocatable  object  modules  to  add  to, 
replace  in,  copy  from,  move  from,  or  delete  from  library ^file.  Each  operation  is  repre¬ 
sented  by  a  code  specifying  the  type  of  operation,  followed  by  the  object  module  name. 
When  an  object  module  is  copied  or  moved  from  the  library  file,  the  drive  and  pathname 
of  the  object  module  are  set  to  the  default  drive,  current  directory,  and  specified  module 
name,  and  the  extension  of  the  object  module  defaults  to  .OBJ.  When  an  object  module  is 
added  or  replaced,  LIB  assumes  a  default  extension  of  .OBJ. 

The  operation  -^name  adds  the  object  module  in  the  file  naine,0&i  to  the  library  file.  This 
operation  can  also  be  used  to  add  the  contents  of  another  entire  object  module  library  file 
to  the  library  file  being  updated,  in  which  case  the  extension  .LIB  must  be  included  in 
name.  The  operation  -name  deletes  the  object  module  name  from  the  library.  The 
operation  -+name  deletes  the  object  module  name  from  the  library  file  and  replaces  it 
with  the  contents  of  the  file  name.OB].  The  operation  copies  the  object  module 
name  from  the  library  file  into  the  file  name.O&iy  which  LIB  creates  in  the  current  direc¬ 
tory.  The  operation  -*name  also  copies  the  object  module  name  from  the  library  file  into 
a  .OBJ  file  but  then  deletes  the  module  from  the  library  file.  (Although  name  must  have 
exactly  the  same  spelling  as  the  name  in  the  library’s  reference  listing,  case  is  not 
significant.) 

Note:  LIB  does  not  actually  delete  object  modules  from  the  specified  library  file.  Instead,  it 
marks  the  selected  object  modules  for  deletion,  creates  a  new  library  file,  and  copies  only 
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the  modules  not  marked  for  deletion  into  the  new  file.  Thus,  if  LIB  is  terminated  for  any 
reason,  the  original  file  is  not  lost.  Enough  space  must  be  available  on  the  disk  for  both  the 
original  library  file  and  the  copy. 

The  list^file  parameter  specifies  the  file  or  character  device  to  receive  a  reference  listing 
for  the  library  file.  Any  valid  drive,  pathname,  and  extension  or  any  valid  character  device, 
such  as  PRN,  is  permitted  (default  =  NUL).  If  this  parameter  is  omitted,  no  listing  is 
generated. 

The  reference  listing  consists  of  two  tables.  The  first  table  contains  all  the  public  symbols 
in  the  object  modules  in  the  library,  listed  alphabetically,  with  each  symbol  followed  by 
the  name  of  the  object  module  in  which  it  is  referenced.  The  second  table  contains  the 
names  of  all  the  object  modules,  listed  alphabetically,  with  each  name  followed  by  the 
offset  from  the  start  of  the  library  file,  the  code  and  data  size,  and  an  alphabetic  listing  of 
the  public  symbols  in  that  object  module. 

The  new^librdry^file  parameter  specifies  the  name  for  the  modified  library  file  that  is 
created.  If  this  parameter  is  omitted,  LIB  gives  the  modified  library  file  the  same  name  as 
the  original  library  file,  and  the  original  library  file  is  renamed  with  a  .BAK  extension. 
When  a  new  library  file  is  being  created,  this  parameter  is  not  necessary. 

When  the  command  line  is  used  to  supply  LIB  with  filenames  and  switches,  typing  a  semi¬ 
colon  character  (;)  after  any  parameter  (except  library^file)  causes  LIB  to  use  the  default 
values  for  the  remaining  parameters.  If  a  semicolon  is  entered  after  library^ file,  LIB  sim¬ 
ply  checks  the  file  for  consistency  and  usability.  (This  is  seldom  necessary,  because 
LIB  checks  each  object  module  for  consistency  before  adding  it  to  the  library.) 

If  the  LIB  command  is  entered  without  any  parameters,  LIB  prompts  the  user  for  each 
parameter  needed.  If  there  are  too  many  operations  to  fit  on  one  line,  the  line  can  be 
ended  with  the  ampersand  character  (&),  causing  LIB  to  repeat  the  Operations:  prompt.  If 
any  response  except  library^file  is  terminated  with  a  semicolon  character,  LIB  uses  the 
default  values  for  the  remaining  filenames.  When  the  parameter  is  followed 

by  a  semicolon  or  a  semicolon  is  entered  at  the  Operations:  prompt,  LIB  takes  no  action 
except  to  verify  that  the  contents  of  the  specified  file  are  consistent  and  usable. 

The  response^file  parameter  allows  the  automation  of  complex  LIB  sessions  involving 
many  files.  A  response  file  contains  ASCII  text  that  corresponds  line  for  line  to  the  re¬ 
sponses  that  are  entered  in  a  normal  interactive  LIB  session,  in  the  form 

library ^file  [  /P:  w] 

[Y] 

{operations^ 

[list_^file] 

[new^library_file]  [;] 

The  response  file  name  must  be  preceded  in  the  command  line  by  the  at  symbol  (@)  and 
can  also  be  preceded  by  a  path  and/or  drive  letter.  If  library^file  is  a  new  file,  the  letter  Y 
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must  appear  by  itself  on  the  second  line  of  the  response  file  to  approve  the  creation  of  a 
library  file.  The  last  line  of  the  response  file  must  end  with  a  semicolon  or  a  carriage  re¬ 
turn.  (LIB  ignores  any  lines  following  a  semicolon.)  If  all  the  parameters  required  by  LIB 
are  not  present  in  the  response  file  or  the  response  file  does  not  end  with  a  semicolon, 

LIB  prompts  the  user  for  the  missing  information. 

Return  Codes 

0  No  error;  LIB  operation  was  successful. 

1  An  error  that  terminated  execution  of  the  LIB  utility  was  encountered. 

Examples 

To  create  a  library  file  named  MYLIB.LIB  and  insert  the  object  files  VIDEO.OBJ, 
COMM.OBJ,  and  DOSINT.OBJ,  type 

OLIB  MYLIB  +VIDEO  +COMM  +DOSINT;  <Enter> 

To  print  a  listing  of  the  object  modules  in  the  library  file  MYLIB.LIB,  type 

OLIB  MYLIB,  PRN  <Enter> 

If  the  LIB  command  is  entered  without  parameters,  the  user  is  prompted  for  the  necessary 
information.  For  example,  if  the  user  wanted  to  add  the  module  VIDEO.OBJ  to  the  library 
file  SLIBC.LIB,  produce  a  reference  listing  in  the  file  SLIBC.LST,  and  produce  a  new  output 
library  file  named  SLIBC2.LIB,  the  following  dialogue  would  take  place: 

OLIB  <Enter> 

Microsoft  (R)  Library  Manager  Version  3.06 

Copyright  (C)  Microsoft  Corp  1983,  1984,  1985,  1986.  All  rights  reserved. 

Library  name:  SLIBC  <Enter> 

Operations:  +VIDEO  <Enter> 

List  file:  SLIBC.LST  <Enter> 

Output  library:  SLIBC2  <Enter> 

Messages 

fUenamei  cannot  access  file. 

LIB  is  unable  to  access  an  object  module  specified  in  a  response  file,  in  the  command  line, 
or  at  the  Operations:  prompt. 

fUenamei  cannot  create  extract  file 

The  object  module  cannot  be  copied  or  moved  from  the  library  file  into  a  separate  disk  file 
called  filename  because  the  root  directory  or  disk  is  full  or  because  fitename  already 
exists  and  is  read-only. 

fUenamei  cannot  create  listing 

The  list  file  specified  in  the  response  file,  in  the  command  line,  or  at  the  List file:  prompt 
cannot  be  created  because  the  root  directory  or  disk  is  full  or  because  filename  already 
exists  and  is  read-only. 
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fUenamei  invalid  format  (xxxx)i  file  ignored. 

The  hexadecimal  signature  byte  or  word  xocxx  of  the  specified  file  was  not  one  of  the 
following  recognized  types:  Microsoft  library,  Intel  library,  Microsoft  object,  or  XENIX 
archive. 

fUenamei  invalid  library  header. 

The  input  library  file  either  is  not  a  library  file  or  is  damaged. 

fUenamei  invalid  library  header;  file  ignored. 

The  input  library  file  is  in  the  wrong  format. 

modulenamei  invalid  object  module  near  location 

The  specified  object  module  has  an  invalid  format  near  the  hexadecimal  offset  indicated. 

modulenamei  module  not  in  Ubrary;  ignored 

The  object  module  specified  in  the  response  file,  in  the  command  line,  or  at  the 
Operations:  prompt  is  not  in  the  specified  input  library  file. 

modulenamei  module  redefinition  ignored 

An  object  module  was  specified  to  be  added  to  a  library  file  but  an  object  module  with  the 
same  name  was  already  in  the  library  file,  or  the  same  object  module  was  specified  twice 
in  an  add  operation  in  the  command  line. 

numberi  page  size  too  small;  ignored 

The  size  specified  with  a  /P:n  switch  must  be  a  power  of  2  between  16  and  32768  bytes, 
inclusive. 

symbol  {modulename)  i  symbol  redefinition  ignored 

The  specified  symbol  was  defined  in  more  than  one  module.  Only  the  first  definition  of  a 
symbol  is  accepted.  All  redefinitions  are  ignored. 

cannot  create  new  library 

The  root  directory  is  full,  or  a  library  file  with  the  same  name  already  exists  and  is  read¬ 
only. 

cannot  open  response  file 

The  specified  response  file  cannot  be  found  or  does  not  exist. 

cannot  rename  old  library 

The  old  library  file  cannot  be  renamed  with  a  .BAK  extension  because  such  a  file  already 
exists  and  is  read-only. 

cannot  reopen  library 

The  old  library  file  could  not  be  reopened  after  it  was  renamed  with  the  .BAK  extension. 
This  error  usually  indicates  damage  to  the  operating  system  or  to  the  disk  directory 
structure. 

comma  or  new  line  missing 

A  comma  or  carriage  return  was  expected  in  the  command  line  but  was  not  found. 
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Do  not  change  diskette  in  drived: 

LIB  may  have  placed  important  temporary  files  on  the  specified  disk.  Do  not  remove  the 
disk  until  the  LIB  operation  is  complete  or  these  files  may  be  lost. 

error  writing  to  cross-reference  file 

The  disk  or  root  directory  is  full. 

error  writing  to  new  library 

The  new  library  file  cannot  be  created  because  the  disk  is  full. 

free:  not  allocated 

This  is  a  serious  problem.  Note  the  circumstances  of  the  failure  and  notify  Microsoft 
Corporation. 

insufficient  memory 

Not  enough  memory  is  available  in  the  transient  program  area  for  LIB  to  successfully  per¬ 
form  the  requested  operations. 

internal  failure 

This  is  a  serious  problem.  Note  the  circumstances  of  the  failure  and  notify  Microsoft 
Corporation. 

Library  does  not  exist.  Create? 

The  specified  library^file  does  not  exist  on  disk.  Respond  with  Y  to  create  the  library 
file;  respond  with  N  to  terminate  the  LIB  utility. 

mark:  not  allocated 

This  is  a  serious  problem.  Note  the  circumstances  of  the  failure  and  notify  Microsoft 
Corporation. 

option  unknown 

The  command  line  included  a  switch  other  than  /P:w. 

output-library  specification  ignored 

An  output  library  file  was  specified  in  addition  to  a  new  library  file.  This  is  only  a  warning. 
The  output  library  file  specification  will  be  disregarded. 

page  size  too  small 

The  page  size  of  an  input  library  file  was  less  than  l6  bytes,  indicating  a  damaged  or  other¬ 
wise  invalid  .LIB  file.  See  LIB  message  number:  page  size  too  small;  ignored. 

syntax  error 

The  command  line  included  an  invalid  parameter  or  switch. 

syntax  error:  illegal  file  specification 

A  command  operator  (such  as  *,  or  +)  was  given  without  an  object  module  name. 

syntax  error:  illegal  input 

The  command  line  included  an  invalid  parameter  or  switch. 
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syntax  error:  option  name  missing 

The  command  line  included  a  forward  slash  (/)  that  was  not  followed  by  P:w. 

syntax  error:  option  value  missing 

The  /P  switch  was  not  followed  by  the  page  size  value  in  bytes. 

terminator  missing 

Either  a  control  character  (such  as  Control-Z)  was  specified  at  the  Output  library:  prompt 
or  the  response  file  line  that  corresponds  to  LIB’s  Output  library:  prompt  was  not  termi¬ 
nated  by  a  carriage  return  or  semicolon. 

too  many  symbols 

The  maximum  number  of  public  symbols  allowed  in  a  library  file  has  been  exceeded.  The 
limit  for  all  object  modules  (combined)  is  4609. 

unexpected  end-of-f lie  on  command  input 

The  response  file  did  not  include  all  the  necessary  LIB  parameters. 

write  to  extract  file  failed 

The  destination  disk  has  insufficient  space  for  the  complete  object  module,  or  the  root 
directory  is  full. 

write  to  library  file  failed 

The  destination  disk  has  insufficient  space  to  create  the  new  library  file,  or  the  root  direc¬ 
tory  is  full. 
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Create  .EXE  File 

Purpose 

Combines  relocatable  object  modules  into  an  executable  (.EXE)  file.  The  Microsoft  Object 
Linker  (LINK)  is  supplied  with  the  Microsoft  Macro  Assembler  (MASM),  C  Compiler,  Pascal 
Compiler,  and  FORTRAN  Compiler.  This  documentation  describes  LINK  version  3.50. 

Syntax 

LINK 

or 

LINK  obj^file[+objL.file, .  AUexe^file]][Xmap^file]][Xlibrary[-^l^^  . .]]]  [options]  [;] 
or 

LINK  @response^file 
where: 
obj^file 

exe^file 

map_file 

library 
response^file 
options 


(more) 


is  the  name  of  a  file  containing  a  relocatable  object  module  produced  by 
MASM  or  by  a  high-level-language  compiler  (default  extension  =  .OBJ), 
is  the  name  of  the  executable  file  to  be  produced  by  LINK  (default  exten¬ 
sion  =  .EXE). 

is  the  name  of  the  file  or  character  device  to  receive  a  listing  of  the  names, 
load  addresses,  and  lengths  of  the  segments  in  exe^  file  (default  =  NUL 
device;  default  extension  =  .MAP). 

is  the  name  of  an  object  module  library  to  be  searched  to  resolve  external 
references  in  the  object  file(s)  (default  extension  =  .LIB), 
is  the  name  of  a  text  file  containing  LINK  parameters  in  the  order  in  which 
they  are  supplied  during  an  interactive  LINK  session, 
specifies  one  or  more  of  the  following  switches.  Switches  can  be  either  up¬ 
percase  or  lowercase. 

/CP:  n  (/CPARMAXALLOC:  w)  Sets  the  maximum  number  of  extra 
memory  paragraphs  required  by  exe_file  (default  =  65535). 
/DS  (/DSALLOCATE)  Loads  the  data  in  DGROUP  at  the  high  end 

of  the  data  segment. 

/DO  (/DOSSEG)  Arranges  segments  according  to  the  Microsoft  lan¬ 

guage  segment-ordering  convention. 

/E  (/EXEPACK)  Compresses  repetitive  sequences  of  bytes  and 

optimizes  exe^file's  relocation  table. 
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Description 


/HI  (/HIGH)  Causes  exe^file  to  be  loaded  as  high  as  possible  in 

memory  when  exe^  file  is  executed. 

/HE  (/HELP)  Lists  LINK  options  on  the  screen.  No  other  switches 

or  filenames  should  be  used  with  this  switch. 

/LI  (/LINENUMBERS)  Copies  line-number  information  (if  avail¬ 

able)  from  obj^file  to  map^file.  If  a  map  file  was  not  speci¬ 
fied,  this  switch  creates  one. 

/M  (/MAP)  Copies  a  list  of  all  public  symbols  declared  in  obj_  file 

to  map^file.  If  a  map  file  was  not  specified,  this  switch  creates 
one. 

/NOD  (/NODEFAULTLIBRARYSEARCH)  Causes  LINK  to  ignore  any 
library  names  inserted  in  the  object  file  by  the  language 
compiler. 

/NOG  (/NOGROUPASSOCIATION)  Causes  LINK  to  ignore  GROUP 
associations  when  assigning  addresses. 

/NOI  (/NOIGNORECASE)  Causes  LINK  to  be  case  sensitive  when 

resolving  external  names. 

/0:n  (/ OVERL AYINTERRUPT :  w)  Overrides  the  interrupt  number 

used  by  the  overlay  manager  (0-255,  default  =  63,  or  3FH). 
This  switch  should  be  used  only  when  linking  with  a  run-time 
module  from  a  language  compiler  that  supports  overlays. 

/P  (/PAUSE)  Causes  LINK  to  pause  and  prompt  the  user  to 

change  disks  before  writing  the  exe^ file. 

/SE:  n  (/SEGMENTS:  n)  Sets  the  maximum  number  of  segments  that 

can  be  processed  (1-1024,  default  =  128). 

/ST :  n  (/STACK:  w)  Sets  the  size  of  the  exe^ file's  stack  segment  to  n 

bytes  (1-65535). 


LINK  combines  relocatable  object  modules  into  an  executable  file  in  the  .EXE  format. 
LINK  can  be  used  with  object  files  produced  by  any  high-level-language  compiler  or  as¬ 
sembler  that  supports  the  Microsoft  object  module  format.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Programming  Tools:  Object  Modules;  The  Microsoft  Object 
Linker. 


The  obj^file  parameter,  which  is  required,  specifies  one  or  more  files  containing  reloca¬ 
table  object  modules.  If  multiple  object  files  are  linked,  their  names  should  be  separated  by 
a  plus  operator  (+)  or  a  space.  If  an  extension  is  not  specified  for  an  object  file,  LINK  sup¬ 
plies  the  extension  .OBJ.  Some  high-level-language  compilers  support  partitioning  of  the 
executable  program  into  a  root  segment  and  one  or  more  overlay  segments  and  include  a 
special  overlay  manager  in  their  libraries;  when  these  compilers  are  used,  the  object  mod¬ 
ules  that  compose  each  overlay  segment  should  be  surrounded  with  parentheses  in  the 
LINK  command  line. 

The  exe_file  parameter  specifies  the  name  of  the  executable  file  that  is  created  by  LINK. 
The  default  is  the  same  filename  as  the  first  object  file,  but  with  the  extension  .EXE. 
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The  map^file  parameter  designates  the  file  or  character  device  to  receive  LINK’S  listing  of 
the  name,  load  address,  and  length  of  each  of  exe^  file's  segments.  The  map  file  also  in¬ 
cludes  the  names  and  load  addresses  of  any  groups  in  the  program,  the  program  entry 
point,  and,  if  the  /M  switch  is  used,  all  public  symbols  and  their  addresses.  If  the  /LI  switch 
is  used  and  if  line  numbers  were  inserted  into  obj_  file  by  the  compiler,  the  starting  ad¬ 
dress  of  each  obj_ file  program  line  is  also  copied  to  map^ file.  The  default  extension  for  a 
map  file  is  .MAP.  If  the  /M  or  /LI  switch  is  used,  a  map  file  is  created  using  the  name  of  the 
specified  .EXE  file  even  if  map_file  is  not  specified.  If  neither  the  /M  nor  the  /LI  switch  is 
used  and  map_file  is  not  specified,  no  listing  is  created. 

The  library  parameter  specifies  the  object  module  library  or  libraries  that  will  be 
searched  to  resolve  external  references  after  all  the  object  files  are  processed.  The  default 
extension  for  library  files  is  .LIB.  Multiple  library  names  should  be  separated  by  plus 
operators  (+)  or  spaces.  A  maximum  of  l6  search  paths  can  be  specified  in  the  LINK  com¬ 
mand  line.  If  a  library  name  is  preceded  by  a  drive  and/or  path,  LINK  searches  only  the 
specified  location.  If  no  drive  or  path  precedes  a  library  name,  LINK  searches  for  library 
files  in  the  following  order: 

1 .  Current  drive  and  directory 

2.  Any  other  library  search  paths  specified  in  the  command  line,  in  the  order  they  were 
entered 

3.  Directories  specified  in  the  LIB=  environment  variable,  if  one  exists 

In  the  following  example,  LINK  searches  only  the  \  ALTLIB  directory  on  drive  A  to  find  the 
library  MATH.LIB.  To  find  the  library  COMMON.LIB,  LINK  searches  the  current  directory 
on  the  current  drive,  then  the  current  directory  on  drive  B,  then  directory  \LIB  on  drive  D, 
and  finally,  any  directories  named  in  the  LIB  environment  variable. 

C>LINK  TEST, , TEST, A:\ALTLIB\MATH. LIB+COMMON+B:+D:\LIB\  <Enter> 

If  default  libraries  are  specified  within  the  object  files  through  special  records  inserted  by 
certain  high-level-language  compilers,  those  libraries  will  be  searched  after  the  libraries 
named  in  the  command  line  or  response  file. 

If  the  LINK  command  is  entered  without  parameters,  LINK  prompts  the  user  for  each  file¬ 
name  needed.  The  default  response  for  each  prompt  (except  the  obj_ file  prompt)  is  dis¬ 
played  in  square  brackets  and  can  be  selected  by  pressing  the  Enter  key.  If  there  are  too 
many  obj^file  or  library  names  to  fit  on  one  line,  the  line  can  be  terminated  by  entering 
a  plus  operator  (+)  and  pressing  the  Enter  key;  LINK  then  repeats  the  prompt.  If  the  user 
ends  any  response  with  a  semicolon  character  (;),  LINK  uses  the  default  values  for  the 
remaining  fields. 

When  the  command  line  contains  filenames  and  switches,  commas  must  be  used  to 
separate  the  obj^file,  exe^file,  map_file,  and  library  parameters.  If  a  filename  is  not 
supplied,  a  comma  must  be  used  to  mark  its  place.  If  the  user  places  a  semicolon  after  any 
parameter  in  the  command  line,  LINK  terminates  the  command  line  at  the  semicolon  and 
uses  the  default  values  for  any  remaining  parameters. 
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The  user  can  automate  complex  LINK  sessions  involving  multiple  files  by  creating  a 
response  file.  The  response^file  parameter  must  be  the  name  of  an  ASCII  file  that  corre¬ 
sponds  line  for  line  to  the  responses  that  are  entered  in  a  normal  interactive  LINK  session. 
The  last  line  of  the  response  file  must  end  with  a  semicolon  character  (  ;)  or  a  carriage 
return.  If  all  parameters  required  by  LINK  are  not  present  in  the  response  file  and  the 
response  file  does  not  end  with  a  semicolon  or  carriage  return,  LINK  prompts  the  user 
for  the  missing  information. 

LINK  supports  many  options  that  can  be  invoked  by  including  a  switch  in  the  command 
line,  as  part  of  the  response  to  a  LINK  prompt,  or  in  a  response  file.  To  simplify  this 
description,  these  switches  are  grouped  according  to  their  functions. 

The  /E,  /HE,  /NOD,  /NOI,  /P,  and  /SE:n  switches  affect  LINK’S  general  operation.  The 
/E  switch  compresses  repetitive  sequences  of  bytes  in  exe^file  and  optimizes  certain 
parts  of  the  relocation  table  in  exe^file's  header.  The  /E  switch  functions  exactly  like  the 
EXEPACK  utility. 

Note:  The  /E  switch  does  not  always  save  a  significant  amount  of  disk  space  and  may  even 
increase  file  size  when  used  with  small  programs  that  have  few  load-time  relocations  or 
repeated  characters.  The  Microsoft  Symbolic  Debugger  (SYMDEB)  utility  cannot  be  used 
with  packed  files. 

The  /HE  switch  displays  the  available  options  on  the  screen.  No  other  switches  or  file¬ 
names  should  be  specified  if  the  /HE  switch  is  used.  The  /NOD  switch  causes  LINK  to 
ignore  any  default  libraries  that  have  been  added  to  the  object  modules  by  the  high-level- 
language  compiler  that  produced  the  modules,  thus  restricting  searches  to  those  libraries 
specified  in  the  command  line  or  response  file.  The  /NOI  switch  causes  LINK  to  be  case 
sensitive  when  resolving  external  references  to  symbols  between  object  modules.  The 
/NOI  switch  is  typically  used  with  object  files  created  by  high-level-language  compilers 
that  differentiate  between  uppercase  and  lowercase  letters. 

The  /P  switch  causes  LINK  to  pause  and  prompt  the  user  before  writing  exe^file  to 
disk,  thus  allowing  the  user  to  exchange  the  disk  used  during  the  linking  operation  for 
another  that  has  more  space  available.  The  /SE:  n  switch  controls  the  number  of  program 
segments  processed  by  LINK.  The  n  must  be  a  decimal,  octal,  or  hexadecimal  number 
from  1  through  1024,  inclusive  (default  =  128).  Octal  numbers  must  have  a  leading  zero; 
hexadecimal  numbers  must  begin  with  Ox. 

The  /M  and  /LI  switches  affect  the  production  and  contents  of  the  optional  map  file. 

The  /M  switch  creates  a  map  file  with  the  same  name  as  exe^ file  or,  if  exe^ file  is  not 
specified,  with  the  same  name  as  the  first  object  file  and  the  extension  .MAP.  The  resulting 
map  file  includes  a  list  of  all  public  symbols  and  their  addresses.  The  /LI  switch  also  cre¬ 
ates  a  map  file  and  includes  line-number  information  if  available  in  the  object  file.  (MASM 
and  some  high-level-language  compilers  do  not  insert  line-number  information  into  object 
files.) 
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The  /D,  /DO,  /NOG,  and  /O:  n  switches  affect  the  structure  of  the  code  in  exe^  file.  Use  of 
the  /D  switch  places  the  data  in  DGROUP  at  the  top  (highest  address)  of  the  memory  seg¬ 
ment  pointed  to  by  the  DS  register,  rather  than  at  the  bottom  (the  default).  The  /DO  switch 
arranges  the  program  segments  according  to  a  convention  expected  by  all  Microsoft  lan¬ 
guage  compilers:  All  segments  with  the  class  name  CODE  are  placed  first  in  the  execut¬ 
able  file;  any  other  segments  that  do  not  belong  to  DGROUP  are  placed  immediately  after 
the  CODE  segments;  all  segments  belonging  to  DGROUP  are  placed  at  the  end  of  the  file. 
The  /NOG  switch  causes  LINK  to  ignore  group  associations  specified  in  the  object  mod¬ 
ules  when  assigning  addresses  to  data  and  code  items;  that  is,  segments  that  would  or¬ 
dinarily  have  been  collected  into  the  same  physical  memory  segment  because  of  their 
association  within  a  GROUP  are  decoupled.  The  /NOG  switch  provides  compatibility  with 
LINK  versions  2.02  and  earlier  and  with  early  versions  of  Microsoft  language  compilers. 
The  /O:  n  switch  controls  the  interrupt  number  used  by  the  resident  overlay  manager  if  the 
linked  program  includes  overlays.  The  number  n  can  be  any  decimal,  octal,  or  hexadeci¬ 
mal  number  in  the  range  0  through  255  (default  =  63,  or  3FH).  Octal  numbers  must  have 
a  leading  zero;  hexadecimal  numbers  must  begin  with  Ox. 

Note:  MASM  and  many  high-level-language  compilers  do  not  include  overlay  managers  in 
their  libraries.  Users  should  check  their  compiler  documentation  to  determine  if  the  /O.n 
switch  can  be  used. 

Warning:  Interrupt  numbers  that  conflict  with  the  software  interrupts  used  to  obtain 
MS-DOS  or  ROM  BIOS  services  or  with  hardware  interrupts  assigned  to  peripheral  device 
controllers  should  not  be  used  in  the  /O.n  switch. 

The  /C: «,  /H,  and  /ST:  n  switches  control  the  information  in  exe^  file's  header  that  affects 
the  behavior  of  the  MS-DOS  system  loader  when  the  file  is  read  from  the  disk  into  RAM  for 
execution.  The  /C:  n  switch  sets  the  maximum  number  of  l6-byte  paragraphs  of  memory 
to  be  made  available  to  the  program  when  it  is  loaded  into  memory,  in  addition  to  the 
memory  required  to  hold  the  program's  code,  data,  and  stacks;  the  default  is  65535,  which 
causes  the  program  to  be  allocated  all  available  memory.  The  /H  switch  causes  the  pro¬ 
gram  to  be  loaded  as  high  as  possible  in  the  transient  program  area  (free  memory),  rather 
than  as  low  as  possible  (the  default).  The  /ST:  n  switch  sets  the  stack  size  (in  bytes)  to  be 
allocated  for  the  program  when  it  is  loaded  and  overrides  any  stack  segment  size  declara¬ 
tions  in  the  original  source  code.  The  number  n  can  be  any  decimal,  octal,  or  hexadecimal 
number  from  1  through  65535;  however  n  must  be  large  enough  to  accommodate  any  ini¬ 
tialized  data  in  the  stack  segment.  Octal  numbers  must  have  a  leading  zero;  hexadecimal 
numbers  must  begin  with  Ox.  If  the  /ST:  w  switch  is  not  used,  LINK  calculates  a  program’s 
stack  size,  basing  the  size  on  the  size  of  any  stack  segments  given  in  the  object  files.  The 
/C:  n  and  /ST :  n  values  in  the  exe_file  header  can  be  altered  after  linking  by  using  the 
EXEMOD  utility. 

If  LINK  is  unable  to  hold  in  RAM  all  the  data  it  is  processing,  it  creates  a  temporary  disk 
file  named  VM.TMP  (Virtual  Memory)  in  the  current  directory  of  the  default  disk  drive.  If  a 
floppy  disk  is  in  the  default  drive,  LINK  issues  a  warning  message  to  prevent  the  user  from 
changing  disks  until  the  LINK  session  is  completed.  After  lINK  finishes  processing,  it 
deletes  the  temporary  file. 
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Warning:  Any  file  named  VM.TMP  that  is  already  on  the  disk  will  be  destroyed  if  LINK 
creates  the  temporary  disk  file. 

Return  Codes 

0  No  errors  or  unresolved  references  were  encountered  during  creation  of  exe_ file. 
1  A  miscellaneous  LINK  error  occurred  that  was  not  covered  by  the  other  return 
codes. 

16  A  data  record  was  too  large  to  process. 

32  No  object  files  were  specified  in  the  command  line  or  response  file. 

33  The  map  file  could  not  be  created. 

66  A  COMMON  area  was  declared  that  is  larger  than  65535  (one  segment). 

96  Too  many  libraries  were  specified. 

144  An  invalid  object  module  (o^/_ fil^  was  detected. 

145  Too  many  TYPDEFs  were  found  in  the  specified  object  modules. 

146  Too  many  group,  segment,  or  class  names  were  found  in  one  object  module. 

147  Too  many  segments  were  found  in  all  the  object  modules  combined,  or  too  many 
segments  were  found  in  one  object  module. 

148  Too  many  overlays  were  specified. 

149  The  size  of  a  segment  exceeded  65535. 

150  Too  many  groups  or  GRPDEFs  were  found  in  one  object  module. 

151  Too  many  external  symbols  were  found  in  one  object  module. 

177  The  size  of  a  group  exceeded  65535. 

Examples 

The  simplest  use  of  LINK  is  to  process  a  single  object  file  to  produce  an  executable  file, 
using  all  the  default  values.  For  example,  to  process  the  file  SHELL.OBJ,  create  an  exe¬ 
cutable  file  named  SHELL.EXE,  and  search  only  the  default  libraries,  type 

C>LINK  SHELL;  <Enter> 

The  semicolon  after  the  filename  causes  LINK  to  use  the  default  values  for  all  other 
parameters. 

To  link  three  object  files  named  SHELL. OBJ,  VIDEO.OBJ,  and  DOSINT.OBJ  into  an  exe¬ 
cutable  file  named  SHELL.EXE  and  search  the  library  DEVLIB.LIB  on  drive  B  before 
searching  any  default  libraries,  type 

OLINK  SHELL+VIDEO+DOSINT, , , B : DEVLIB  <Enter> 

If  the  LINK  command  is  entered  without  parameters,  LINK  prompts  the  user  for  the 
necessary  information.  For  example,  the  following  interactive  session  links  the  file 
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MENUMGR.OBJ  into  the  executable  file  MENUMGR.EXE,  creates  a  map  file  named 
MENUMGR.MAP,  and  searches  the  math  floating-point  emulator  library  EM.LIB  before 
any  default  libraries: 

OLINK  <Enter> 

Microsoft  (R)  8086  Object  Linker  Version  3.05 

Copyright  (C)  Microsoft  Corp  1983,1984,1985.  All  rights  reserved. 

Object  Modules  [.OBJ]:  MENUMGR  <Enter> 

Run  File  [MENUMGR.EXE]:  <Enter> 

List  File  [NUL.MAP] :  MENUMGR  <Enter> 

Libraries  [.LIB]:  EM  <Enter> 

Messages 

filename  is  not  a  valid  library 

The  file  specified  as  an  object  module  library  either  is  corrupt  or  is  not  a  library  in  the 
format  created  by  the  Microsoft  LIB  utility. 

About  to  generate  .EXE  file 

Change  diskette  in  drived  and  press  <ENTER> 

The  /P  switch  was  used  in  the  command  line.  LINK  is  prompting  the  user  to  change  disks 
before  LINK  creates  the  file  containing  the  executable  program. 

Ambiguous  switch  error:  ” 

A  valid  switch  was  not  entered  after  a  forward  slash  (/)  in  the  command  line. 

Array  element  size  mismatch 

A  FAR  communal  array  was  declared  with  two  or  more  different  array-element  sizes  (for 
example,  once  as  an  array  of  characters  and  once  as  an  array  of  real  numbers).  This  error 
occurs  only  with  programs  produced  by  the  Microsoft  C  Compiler  or  other  compilers  that 
support  FAR  communal  arrays;  it  does  not  occur  with  object  files  produced  by  MASM. 

Attempt  to  access  data  outside  segment  bounds 

A  data  record  in  an  object  module  specified  data  extending  beyond  the  end  of  a  segment. 
This  is  a  translator  error.  Note  which  compiler  or  assembler  produced  the  invalid  object 
module  and  notify  Microsoft  Corporation. 

Attempt  to  put  segment  name  in  more  than  one  group  in  file  filename 

A  segment  was  declared  to  be  a  member  of  two  groups.  Correct  the  source  code  and  re¬ 
create  the  object  modules. 

Bad  value  for  cparMaxAlloc 

The  value  specified  using  the  /C:  n  option  is  not  in  the  range  1  through  65535. 

Cannot  create  temporary  file 

The  destination  disk  has  insufficient  space  for  the  temporary  file,  or  the  root  directory  is 
full. 
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Cannot  find  file  filename 
Change  diskette  and  press  <ENTER> 

The  specified  object  file  cannot  be  found  in  the  current  drive. 

Cannot  find  library:  filename 
Enter  new  file  spec: 

The  specified  library  file  cannot  be  found  or  does  not  exist.  Enter  the  correct  drive  letter, 
check  the  spelling  of  the  filename  and  path,  or  make  sure  that  the  LIB  environment  vari¬ 
able  has  been  set  up  properly. 

Cannot  nest  response  files 

A  response  file  was  named  within  a  response  file.  Revise  the  response  file  to  eliminate  the 
nested  file. 

Cannot  open  list  file 

The  destination  disk  has  insufficient  space  for  the  listing,  or  the  root  directory  is  full. 

Cannot  open  response  file:  filename 

LINK  cannot  find  the  specified  response  file. 

Cannot  open  run  file 

The  destination  disk  has  insufficient  space  for  the  .EXE  file,  or  the  root  directory  is  full. 

Cannot  open  temporary  file 

The  destination  disk  has  insufficient  space  for  the  temporary  file,  or  the  root  directory  is 
full. 

Cannot  reopen  list  file 

The  original  disk  was  not  replaced  when  requested.  Restart  LINK. 

Common  area  longer  than  65536  bytes 

The  program  has  more  than  64  KB  of  communal  variables.  This  error  occurs  only  with 
programs  produced  by  the  Microsoft  C  Compiler  or  other  compilers  that  support  commu¬ 
nal  variables. 

Data  record  too  large 

An  LEDATA  record  (in  an  object  module)  contains  more  than  1024  bytes  of  data.  This  is  a 
symptom  of  an  error  in  the  compiler  used  to  generate  the  object  module.  Document  the 
circumstances  and  contact  Microsoft  Corporation. 

Dup  record  too  large 

An  LIDATA  record  (in  an  object  module)  contains  more  than  512  bytes  of  data.  This  error 
may  be  caused  by  a  complex  structure  definition  or  by  a  series  of  deeply  nested  DUP 
operators. 

File  not  suitable  for  /EXEPACK,  relink  without 

The  file  linked  with  the  /E  switch  would  haye  been  smaller  if  it  had  not  been  compressed. 
Relink  without  the  /E  switch. 
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Fixup  overflow  near  number  in  segment  name  in  filename  offset  number 

A  group  is  larger  than  64  KB,  the  original  source  file  contains  an  intersegment  short  jump 
or  intersegment  short  call,  the  name  of  a  data  item  conflicts  with  that  of  a  library  sub¬ 
routine,  or  an  EXTRN  declaration  is  placed  inside  the  wrong  segment. 

Incorrect  DOS  version,  use  DOS  2,0  or  later 

LINK  uses  the  extended  file  management  calls  to  provide  path  support  and,  thus,  does  not 
work  with  versions  of  MS-DOS  earlier  than  2.0. 

Insufficient  stack  space 

Not  enough  memory  is  available  to  run  LINK. 

Interrupt  number  exceeds  255 

The  number  specified  in  the  /O:  n  switch  is  not  in  the  range  0  through  255. 

Invalid  numeric  switch  specification 

An  incorrect  value  was  entered  with  one  of  the  LINK  options. 

Invalid  object  module 

One  of  the  object  modules  is  invalid.  Recompile  the  source  file.  If  the  error  persists  after 
recompiling,  document  the  circumstances  and  contact  Microsoft  Corporation. 

NEAR/HUGE  confUct 

Conflicting  NEAR  and  HUGE  definitions  were  given  for  a  communal  variable.  This  error 
occurs  only  with  programs  produced  by  the  Microsoft  C  Compiler  or  other  compilers  that 
support  communal  variables. 

Nested  left  parentheses 

An  opening  (left)  parenthesis  is  needed  on  the  left  side  of  an  overlay  module. 

Nested  right  parentheses 

A  closing  (right)  parenthesis  is  needed  on  the  right  side  of  an  overlay  module. 

No  object  modules  specified 

No  object  file  names  were  specified  in  the  command  line  or  response  file. 

Object  not  found 

One  of  the  object  files  specified  in  the  command  line  was  not  found. 

Out  of  space  on  list  file 

The  destination  disk  has  insufficient  space  for  the  listing. 

Out  of  space  on  run  file 

The  destination  disk  has  insufficient  space  for  the  .EXE  file. 

Out  of  space  on  scratch  file 

The  disk  in  the  default  drive  has  insufficient  space  for  temporary  files. 

Overlay  manager  symbol  already  defined:  name 

A  symbol  name  was  defined  that  conflicts  with  one  of  the  special  overlay  manager  names. 
Use  another  symbol  name. 
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Please  replace  original  diskette 
in  drived  and  press  <ENTER> 

The  /P  switch  was  specified  in  the  command  line  and  the  disk  to  receive  the  .EXE  file  pro¬ 
duced  by  LINK  has  already  been  inserted.  This  message  indicates  that  the  .EXE  file  was 
successfully  created  and  that  the  original  disk  should  again  be  placed  in  the  drive. 

Relocation  table  overflow 

More  than  32768  long  calls,  long  jumps,  or  other  long  pointers  were  found  in  the  program. 
The  program  may  need  to  be  restructured  to  reduce  the  number  of  FAR  references.  (Pascal 
and  FORTRAN  users  should  try  turning  off  the  debugging  option  before  restructuring  the 
program.) 

Response  line  too  long 

A  line  in  a  response  file  had  more  than  127  characters. 

Segment  limit  set  too  high 

The  number  specified  in  the  /SE:  n  switch  was  not  in  the  range  1  through  1024. 

Segment  limit  too  high 

Not  enough  memory  is  available  for  LINK  to  allocate  tables  to  describe  the  number  of 
segments  requested  (default  =  128  or  the  number  specified  in  the  /SE:  n  switch).  Use  the 
/SE:  n  switch  to  specify  a  smaller  number  of  segments,  or  alter  the  system  configuration 
to  increase  the  amount  of  free  memory. 

Segment  size  exceeds  64K 

The  program  is  a  small-model  program  with  more  than  64  KB  of  code  or  data,  a  compact- 
model  program  with  more  than  64  KB  of  code,  or  a  medium-model  program  with  more 
than  64  KB  of  data.  Selection  of  a  different  model  or  alteration  of  the  program  code  may 
be  required  to  successfully  complete  the  LINK  process. 

Stack  size  exceeds  65536  bytes 

The  size  specified  for  the  stack  in  the  /ST:  w  switch  was  too  large,  or  the  combined  length 
of  multiple  declared  stack  segments  exceeded  64  KB. 

Symbol  already  defined:  "^symboV" 

One  of  the  special  overlay  symbols  required  for  overlay  support  was  previously  defined. 

Symbol  defined  more  than  once:  in  file 

A  symbol  has  been  defined  more  than  once  in  the  object  module.  Remove  the  extra  sym¬ 
bol  definition. 

Symbol  table  overflow 

The  program  has  more  than  256  KB  of  symbolic  information  (publics,  externals,  segments, 
groups,  classes,  files,  and  so  on).  Eliminate  as  many  public  symbols  as  possible,  combine 
modules  and/or  segments,  and  recreate  the  object  files. 

Terminated  by  user 

Ctrl-C  or  Ctrl-Break  was  pressed,  causing  the  LINK  session  to  be  terminated  prematurely. 
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Too  many  external  symbols  in  one  module 

An  object  module  contains  more  than  the  limit  of  1023  external  symbols. 

Too  many  group-,  segment-,  and  class-names  in  one  module 

One  of  the  object  modules  for  the  program  contains  too  many  group,  segment,  and  class 
names.  The  source  file  for  the  object  module  may  need  to  be  divided  or  restructured. 

Too  many  groups 

The  program  defines  more  than  nine  groups  (including  DGROUP).  Groups  must  be  com¬ 
bined  or  eliminated. 

Too  many  GRPDEFs  in  one  module 

LINK  encountered  more  than  nine  group  definitions  (GRPDEFs)  in  a  single  object  module. 
Reduce  the  number  of  GRPDEFs  or  split  the  object  module. 

Too  many  libraries 

More  than  16  libraries  were  specified.  Combine  libraries  or  use  object  modules  that  require 
fewer  libraries. 

Too  many  overlays 

The  program  defines  more  than  63  overlays.  Reduce  the  number  of  overlays. 

Too  many  segments 

The  program  has  more  than  the  maximum  number  of  segments  as  specified  by  the  default 
of  128  or  with  the  /SE:  n  switch.  Use  the  /SE:  n  switch  to  specify  a  greater  number  of 
segments. 

Too  many  segments  in  one  module 

An  object  module  has  more  than  255  segments.  Split  the  module  or  combine  segments. 

Too  many  TYPDEFs 

An  object  module  contains  too  many  TYPDEF  records  (these  records  describe  communal 
variables).  This  error  occurs  only  with  programs  produced  with  the  Microsoft  C  Compiler 
or  other  compilers  that  support  communal  variables. 

Unexpected  end-of-file  on  library 

This  message  may  indicate  that  the  disk  containing  the  library  in  use  was  removed 
prematurely. 

Unexpected  end-of-file  on  scratch  file 

The  disk  containing  VM.TMP  was  removed. 

Unmatched  left  parenthesis 

A  syntax  error  was  detected  in  the  specification  of  an  overlay  structure.  Refer  to  the  lan¬ 
guage  compiler  manual  for  instructions  on  specifying  overlays  to  LINK. 

Unmatched  right  parenthesis 

A  syntax  error  was  detected  in  the  specification  of  an  overlay  structure.  Refer  to  the  lan¬ 
guage  compiler  manual  for  instructions  on  specifying  overlays  to  LINK. 
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Unrecognized  switch  error:  ^^option^^ 

An  unrecognized  character  was  entered  after  a  forward  slash  (/)  in  the  command  line. 

Unresolved  COMDEF;  Microsoft  internal  error 

This  is  a  serious  problem.  Note  the  circumstances  of  the  failure  and  contact  Microsoft 
Corporation. 

Unresolved  externals:  list 

A  symbol  was  declared  external  (EXTRN)  in  one  object  module  but  was  not  declared 
PUBLIC  in  the  object  module  in  which  it  was  defined,  or  a  necessary  library  specification 
was  omitted  from  the  command  line  or  response  file. 

VM.TMP  is  an  illegal  file  name 
and  has  been  ignored 

VM.TMP  was  specified  as  an  object  file  name.  If  an  object  file  named  VM.TMP  exists, 
rename  it. 

Warning:  load-high  disables  exepack 

The  /H  and  /E  switches  cannot  be  used  at  the  same  time. 

Warning:  no  stack  segment 

The  program  contains  no  segment  with  the  STACK  combine  type.  This  message  can  be 
ignored  if  there  is  a  specific  reason  for  not  defining  a  stack  (for  example,  if  the  .EXE  file 
will  subsequently  be  converted  to  a  .COM  file)  or  for  defining  one  without  the  STACK 
combine  type. 

WARNING:  Segment  longer  than  reliable  size 

Although  code  segments  can  be  as  long  as  65536  bytes,  code  segments  longer  than 
65500  bytes  can  be  unreliable  on  the  Intel  80286  microprocessor.  Reduce  all  code  seg¬ 
ments  to  65500  bytes  or  less. 

Warning:  too  many  public  symbols 

The  /M  switch  was  used  to  request  a  sorted  listing  of  public  symbols  in  the  map  file,  but 
there  are  too  many  symbols  to  sort.  LINK  will  produce  an  unsorted  listing  instead. 
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MAKE 

Maintain  Programs 


Purpose 

Interprets  a  text  file  of  commands  to  compare  dates  of  files  and  carry  out  other  operations 
on  the  basis  of  the  comparison.  MAKE  is  customarily  used  to  update  the  executable  ver¬ 
sion  of  a  program  after  a  change  to  one  or  more  of  its  source  files.  The  MAKE  utility  is  sup¬ 
plied  with  the  Microsoft  Macro  Assembler  (MASM),  C  Compiler,  and  FORTRAN  Compiler. 
This  documentation  describes  MAKE  version  4.05. 


Syntax 

MAKE  [/D]  [/I]  [/N]  [/S]  [name^value . ,  A  filename 
where: 


filename 

name^value 

/D 

/I 

/N 

/S 


is  an  ASCII  text  file  that  contains  MAKE  dependency  statements,  com¬ 
mands,  macro  definitions,  and  inference  rules, 
declares  a  MAKE  macro,  associating  a  specific  value  with  the  dummy 
parameter  name. 

displays  the  last  modification  date  of  each  file  as  it  is  scanned, 
causes  MAKE  to  ignore  exit  codes  returned  by  programs  called  by 
filename. 

displays  but  does  not  execute  the  commands  in  filename. 

selects  “silent”  mode  (commands  are  not  displayed  as  they  are  executed). 


Note:  Switches  can  be  either  uppercase  or  lowercase  and  can  be  preceded  by  a  dash  (-) 
instead  of  a  forward  slash  (/).  Versions  of  MAKE  earlier  than  4.0  have  no  switches. 


Description 

The  MAKE  utility  allows  maintenance  of  complex  programs  to  be  automated.  Its  basic 
operation  is  to  compare  the  dates  of  files  and  to  carry  out,  or  not  carry  out,  an  associated 
list  of  commands  on  the  basis  of  the  comparison. 


The  filename  parameter  specifies  an  ASCII  text  file  often  referred  to  as  a  make  file.  By 
convention,  filename  is  the  same  as  the  name  of  the  executable  program  being  main¬ 
tained,  but  without  an  extension.  A  make  file  can  contain  the  following  types  of  entries: 

•  Dependency  statements 

•  Commands 

•  Macro  definitions 

•  Inference  rules 

•  Comments 
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The  basic  form  of  a  make  file  is  a  dependency  statement  followed  by  one  or  more  valid 
MS-DOS  command  lines: 

targetfile:  dependentfilel  [dependentfile2 . . .  ] 
commandl 
[command2] 

where  targetfile  designates  the  file  that  may  need  updating,  dependentfile  is  a  source  file 
or  files  on  which  targetfile  depends,  and  commandl,  command2,  and  so  forth  are  any 
valid  MS-DOS  internal  commands  or  external  programs.  These  commands  or  programs 
are  executed  only  if  the  date  and  time  stamps  of  any  dependent  file  are  more  recent  than 
those  of  the  target  file  or  if  the  target  file  does  not  exist.  Only  one  target  file  can  be  speci¬ 
fied.  Any  number  of  dependent  files  can  be  included;  each  dependent  filename  must  be 
separated  from  the  next  by  at  least  one  space.  If  too  many  dependent  files  are  included  to 
fit  on  a  single  line,  the  line  can  be  terminated  with  a  backslash  character  (\)  and  the  list 
continued  on  the  next  line. 

Any  number  of  MS-DOS  command  lines  can  follow  a  dependency  statement.  The  last 
command  line  should  be  followed  by  a  blank  line  to  set  it  off  from  the  next  MAKE  entry.  It 
is  recommended  that  each  command  line  include  a  leading  space  or  tab  character  for  com¬ 
patibility  with  future  versions  of  MAKE  and  existing  versions  of  XENIX  MAKE. 

A  macro  definition  takes  the  form 

name^value 

where  both  name  and  value  are  any  string.  Whenever  name  is  referenced  in  the  make 
file  in  the  form  %inam^,  name  is  replaced  by  the  string  value  before  the  statement  that 
contains  it  is  evaluated  or  executed.  Macro  definitions  can  be  nested,  although  very  com¬ 
plex  macro  definitions  can  result  in  the  premature  termination  of  the  MAKE  process  be¬ 
cause  of  lack  of  memory.  If  name  is  not  defined  in  the  file  but  is  defined  in  the  system 
environment  block  by  a  previous  SET  command,  %{Yiam^  is  replaced  by  the  string  follow¬ 
ing  the  equal  sign  (=)  in  the  environment  block.  If  the  command  line  contains  a  parameter 
of  the  form  name^value,  the  command  line  overrides  any  definition  of  name  in  the  make 
file  or  in  the  environment  block.  Thus,  the  precedence  for  macro  definitions  with  the 
same  name  is 

1.  Command  line 

2.  Make  file 

3.  Environment  block 

MAKE  contains  several  special  macros  that  make  it  more  convenient  to  form  commands: 


Macro  Action 

$♦  Substitutes  as  the  base  portion  of  targetfile  (the  filename  without  the 

extension). 

$@  Substitutes  as  the  complete  targetfile  name. 

$*♦  Substitutes  as  the  complete  dependentfile  list. 
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An  inference  rule  specifies  a  series  of  commands  to  be  carried  out  for  a  matching  depen¬ 
dency  statement  that  is  not  followed  by  its  own  list  of  commands.  Inference  rules  allow  a 
set  of  commands  to  be  applied  to  more  than  one  targetfile:  dependentfile  description, 
eliminating  repetition  of  the  same  set  of  commands  for  several  descriptions.  An  inference 
rule  takes  the  form 

.dependentextension.targetextension: 

commandl 

[command2] 


Whenever  MAKE  finds  a  dependency  statement  not  followed  by  any  commands,  the 
utility  first  searches  the  make  file  for  an  inference  rule.  If  MAKE  doesn’t  find  an  inference 
rule  in  the  make  file,  the  utility  then  searches  the  current  drive  and  directory  (or  any  di¬ 
rectories  specified  with  the  MS-DOS  PATH  command)  for  the  tools  initialization  file 
(TOOLS.INI)  and  searches  the  [make] section  of  TOOLS.INI  for  an  inference  rule  that 
matches  the  extensions  of  the  target  file  and  dependent  files  in  the  dependency  statement. 

A  make  file  can  contain  any  number  of  comment  lines.  If  a  comment  is  placed  where 
MAKE  expects  to  find  a  command,  the  comment  must  be  on  a  separate  line  and  must  have 
the  pound  character  (#)  as  the  first  character  of  the  line.  Elsewhere,  a  pound  character  and 
following  comment  text  can  be  placed  either  on  a  line  alone  or  after  the  last  dependent  file 
or  command  listed  on  a  line.  Characters  appearing  on  a  line  after  the  pound  character  are 
ignored  during  execution. 

The  /D,  /N,  and  /S  switches  affect  MAKE’s  output  to  the  display  while  MAKE  is  executing. 
The  /D  switch  causes  the  last  modification  date  of  each  file  to  be  displayed  as  the  file  is 
scanned.  The  /N  switch  causes  the  commands  in  the  make  file  to  be  expanded  and  dis¬ 
played,  but  not  executed;  this  is  useful  for  determining  the  result  of  a  specific  MAKE 
process  without  first  examining  the  file  dates  and  without  recompiling  or  relinking  files. 
The  /S  switch  selects  “silent”  mode,  in  which  commands  are  not  displayed  as  they  are 
executed. 

The  /I  switch  causes  MAKE  to  ignore  error  codes  returned  by  the  compilers,  assemblers, 
linkers,  or  other  programs  called  by  the  make  file.  When  the  /I  switch  is  used,  the  MAKE 
process  proceeds  to  completion  regardless  of  errors  instead  of  terminating  immediately  as 
it  ordinarily  would,  but  the  resulting  files  may  not  be  executable. 

Return  Codes 

0  No  error;  the  MAKE  process  was  successful. 

1  Processing  was  terminated  because  of  a  fatal  error  by  MAKE  or  by  one  of  the  pro¬ 
grams  called  by  MAKE. 


Section  IV:  Programming  Utilities  1001 


MAKE 


Example 

Assume  that  the  file  SHELL  contains  the  following  MAKE  dependency  statements  and 
commands: 

video. obj:  video. asm 
masm  video; 

shell. obj:  shell. c 
msc  shell; 

shell.exe:  shell. obj  video. obj 

link  /map  shell+video, shell, shell, slibc2 

The  SHELL  file  asserts  that  the  executable  program  SHELL.EXE  is  composed  of  the  files 
SHELL.OBJ  and  VIDEO.OBJ,  which  are  in  turn  compiled  or  assembled  from  the  source 
files  SHELL.C  and  VIDEO.ASM.  To  update  the  file  SHELL.EXE  if  either  of  the  source  files 
for  its  constituent  modules  has  been  changed,  type 

C>MAKE  SHELL  <Enter> 

Messages 

fatal  error  UlOOl ;  macro  definition  larger  than  512 

A  single  macro  was  defined  to  have  a  value  string  longer  than  the  512-byte  maximum. 
Rewrite  the  make  file  to  use  two  or  more  short  lines  instead  of  one  long  line. 

fatal  error  U1002:  infinitely  recursive  macro 

The  macros  defined  in  the  make  file  form  a  circular  chain. 

fatal  error  U1003s  out  of  memory 

The  make  file  cannot  be  processed  because  insufficent  memory  is  available  in  the  tran¬ 
sient  program  area.  Split  the  make  file  into  two  make  files  or  reconfigure  the  system  to 
increase  available  memory. 

fatal  error  U1004:  syntax  error  :  macro  name  missing 

A  macro  name  is  missing  from  the  left  side  of  the  equal  sign  (=). 

fatal  error  U1005:  syntax  error  :  colon  missing 

A  line  that  should  be  a  dependency  statement  lacks  the  colon  that  separates  a  target  file 
from  its  dependent  files.  MAKE  expects  any  line  that  follows  a  blank  line  to  be  a  depen¬ 
dency  statement. 

fatal  error  U1006:  targetname  :  macro  expansion  larger  than  512 

A  single  macro  expansion,  plus  the  length  of  any  string  to  which  it  may  be  concatenated, 
is  longer  than  512  bytes.  Rewrite  the  make  file  to  use  two  or  more  short  lines  instead  of  one 
long  line. 

fatal  error  U1007:  multiple  sources 

An  inference  rule  has  been  defined  more  than  once  in  the  make  file. 
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fatal  error  U1008:  filename  :  cannot  find  file 

The  specified  file  does  not  exist. 

fatal  error  U1009:  command  :  argument  list  too  long 

A  command  line  in  the  make  file  is  longer  than  128  characters  (the  maximum  MS-DOS 
allows). 

fatal  error  UlOlO:  filename  :  permission  denied 

The  specified  file  is  read-only. 

fatal  error  UlOll :  not  enough  memory 

Memory  is  insufficient  in  the  transient  program  area  to  execute  a  program  listed  in  the 
make  file.  Reconfigure  the  system  to  increase  available  memory,  if  necessary. 

fatal  error  U1012:  filename  :  unknown  error 

This  is  a  serious  problem.  Note  the  circumstances  of  the  failure  and  notify  Microsoft 
Corporation. 

fatal  error  U1013:  command  :  error  retumcode 

One  of  the  programs  or  commands  called  by  MAKE  was  not  able  to  execute  correctly. 
MAKE  terminates  and  displays  the  error  code  from  the  program  that  failed. 

warning  U4000:  filename  :  target  does  not  exist 

The  target  file  does  not  already  exist.  The  dependency  statement  is  evaluated  as  though 
the  target  file  exists  and  has  a  date  earlier  than  that  of  any  of  the  dependent  files. 

warning  U4001:  dependent  filename  does  not  exist; 
tea:%et  filename  not  built 

One  of  the  dependent  files  does  not  exist  or  could  not  be  found,  so  MAKE  terminated 
without  creating  a  new  target  file. 

warning  U4013:  command  :  error (ignored) 

One  of  the  programs  or  commands  called  by  MAKE  did  not  execute  successfully  and  has 
returned  the  specified  return  code.  Because  MAKE  was  run  with  the  /I  switch,  MAKE 
ignores  the  error  and  continues  processing  the  make  file. 

warning U40l4:  usage  :  make[/n][/d][/i][/s][name»value  ...]file 

An  error  was  detected  in  the  MAKE  command  line. 
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MAPSYM 

Create  Symbol  File  for  SYMDEB 


Purpose 

Processes  a  map  file  generated  by  the  Microsoft  Object  Linker  (LINK)  to  create  a  special 
symbol  file  for  use  with  SYMDEB,  the  symbolic  debugging  program.  The  MAPSYM  utility 
is  supplied  with  the  Microsoft  Macro  Assembler  (MASM).  This  documentation  describes 
MAPSYM  version  4.0. 

Syntax 

MAPSYM  [/L]  map^file 
where: 

map^ file  is  a  map  file  produced  by  LINK  (default  extension  =  .MAP). 

/L  causes  information  about  the  symbol  file  to  be  displayed  as  it  is  created. 

Note:  The  /L  switch  can  be  either  uppercase  or  lowercase  and  can  be  preceded  by  a  dash 
(-)  instead  of  a  forward  slash  (/). 

Description 

LINK  combines  relocatable  object  records  (produced  by  MASM  or  a  high-level-language 
compiler)  into  an  executable  program,  which  is  stored  in  a  specially  formatted  file  with  a 
.EXE  extension.  LINK  can  also  produce  an  optional  map  file  that  contains  information 
about  public  symbols  and  addresses  in  the  linked  program.  The  map  file  is  an  ordinary 
ASCII  text  file  and  has  a  default  extension  of  .MAP. 

To  create  a  map  file  to  use  with  MAPSYM,  the  LINK  command  line  should  include  the 
/MAP  switch,  which  creates  the  file,  and  the  /LINENUMBERS  switch,  which  includes  line 
numbers.  See  PROGRAMMING  UTILITIES:  link. 

The  MAPSYM  utility  processes  a  map  file  into  a  special  symbol  file  that  can  be  used  by 
SYMDEB.  A  drive  and  pathname  can  be  specified  if  the  map  file  is  not  in  the  current  direc¬ 
tory.  If  a  file  extension  is  not  specified,  .MAP  is  assumed. 

The  symbol  file  created  by  MAPSYM  is  placed  in  the  current  directory  and  has  the  same 
name  as  the  map  file  but  has  the  extension  .SYM.  It  can  contain  a  maximum  of  1024  seg¬ 
ments  (or  as  many  segments  as  can  fit  into  available  memory)  and  10,000  symbols  per 
segment.  See  PROGRAMMING  UTILITIES:  symdeb. 

When  the  /L  switch  precedes  map^file  in  the  command  line,  MAPSYM  displays  the 
names  of  groups  defined  in  the  program  described  by  the  map  and  symbol  files,  plus  the 
program’s  starting  address.  The  /L  switch  does  not  affect  the  format  of  the  symbol  file  that 
is  generated. 
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Return  Codes 

0  No  error;  the  MAPSYM  process  was  successful. 

1  Processing  was  terminated  because  of  a  write  failure,  because  the  map  file  specified 
does  not  exist,  or  because  the  symbol  file  could  not  be  created. 

4  Processing  was  terminated  because  an  unexpected  end-of-file  mark  was  detected, 
because  too  many  segments  exist  in  the  map  file,  because  no  public  symbols  exist  in 
the  map  file,  or  because  not  enough  memory  is  available  to  create  the  symbol  file. 

Example 

To  convert  the  file  HELLO.MAP,  which  was  produced  by  assembling  and  linking  the  file 
HELLO.ASM,  to  a  symbol  file  that  can  be  used  by  SYMDEB,  type 

C>MAPSYM  /L  HELLO  <Enter> 

MAPSYM  displays  the  following: 

Microsoft  (R)  Symbol  File  Generator  Version  4.00 

Copyright  (C)  Microsoft  Corp  1984,  1985.  All  rights  reserved. 

Building:  HELLO. SYM 
HELLO.MAP 

Program  entry  point  at  0000:0100 
HELLO  0  segment 

The  symbol  file  produced  by  MAPSYM  symbol  has  the  name  HELLO.SYM. 

Messages 

Can’t  create:  <Jtlename> 

The  drive  specified  does  not  exist,  the  current  disk  or  directory  is  full,  or  the  output  file 
already  exists  and  is  read-only. 

Can’t  open  MAP  file:  <fllename> 

The  file  named  in  the  command  line  does  not  exist. 

DOS  2.0  or  later  required 

MAPSYM  does  not  work  with  versions  of  MS-DOS  earlier  than  2.0. 

mapsym:  out  of  memory 

System  memory  is  insufficient  to  process  the  map  file. 

mapsym:  segment  table  («)  exceeded. 

More  than  1024  segments  have  been  used  in  the  map  file.  The  number  displayed  is  the 
total  number  of  segments  in  the  map  file. 

No  public  symbols 

Re-link  file  with  the  /M  switch! 

The  map  file  created  by  LINK  does  not  include  a  list  of  public  names.  The  .EXE  file  must 
be  relinked  using  the  /MAP  switch  to  generate  a  map  file  that  can  be  used  with  MAPSYM. 
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Unexpected  eof  reading:  <filename> 

The  map  file  contains  no  symbols,  is  corrupt,  or  is  otherwise  invalid.  The  .EXE  file  must  be 
relinked  and  a  new  map  file  generated. 

usage:  MAPSYM  [/I]  mapUst 

A  syntax  error  was  detected  in  the  command  line. 

Write  fail  on:  <fllename> 

An  error  occurred  during  the  creation  of  the  output  file. 
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MASM 

Microsoft  Macro  Assembler 

Purpose 

Translates  an  assembly-language  source  program  into  a  relocatable  object  module.  MASM 
is  part  of  the  Microsoft  Macro  Assembler  (MASM)  retail  package.  This  documentation 
describes  MASM  version  4.0. 

Syntax 

MASM 

or 

MASM  source^file  [Jofe7l&c^_//fe][Jto_//fe][,[cr^//fe]]]]  [options]  [;] 
where: 

source^file  is  the  name  of  the  file  containing  the  assembly-language  source  code 
(default  extension  =  .ASM). 

objects  file  is  the  name  of  the  file  to  receive  the  assembled  object  module  (default 

extension  =  .OBJ). 

list^file  is  the  name  of  the  file  or  device  to  receive  the  assembly  listing 

(default  =  NUL).  (If  destination  =  file,  default  extension  =  .LST.) 
cref^  file  is  the  name  of  the  cross-reference  file  to  receive  information  for  later 

processing  by  the  CREF  utility  (default  =  NUL).  (If  destination  =  file, 
default  extension  =  .CRF.) 

options  is  one  or  more  switches  from  the  list  below. 

/A  Writes  the  program  segments  in  alphabetic  order. 

/B«  Sets  the  size  of  the  source-file  buffer  in  kilobytes  (1-63, 
default  =  32). 

/C  Creates  a  cross-reference  (.CRF)  file. 

/D  Adds  a  first-pass  program  listing  to  list^  file  if  a  list  file  was 

specified  (default  =  second-pass  listing  only). 

/^symbol  Defines  symbol  as  a  null  text  string. 

/E  Assembles  code  for  an  8087/80287  emulator. 

/Ipath  Defines  a  directory  to  be  searched  for  include  files. 

/L  Creates  a  list  (.LST)  file  with  line-number  information. 

/ML  Preserves  case  sensitivity  in  all  symbol  names. 

(more) 
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/MU  Converts  all  lowercase  names  to  uppercase  names. 

/MX  Preserves  lowercase  in  public  and  external  names  only. 

/N  Suppresses  generation  of  tables  of  macros,  structures,  records, 

groups,  segments,  and  symbols  at  the  end  of  the  list  file. 

/P  Checks  for  impure  code  in  80286  protected  mode;  has  no 

effect  unless  the  .286P  directive  is  included  in  the  source  file. 
/R  Assembles  code  for  an  8087/80287  math  coprocessor. 

/S  Arranges  program  segments  in  order  of  occurrence. 

/T  Selects  terse  mode,  suppressing  all  messages  generated  during 

assembly  except  error  messages. 

/V  Selects  verbose  mode,  displaying  the  number  of  lines  and 

symbols  at  the  end  of  assembly. 

/X  Includes  false  conditionals  in  the  list  file. 

/Z  Displays  source  lines  with  errors  during  assembly. 

Note:  Switches  can  be  either  uppercase  or  lowercase  and  can  be  preceded  by  a  dash  (-) 
instead  of  a  forward  slash  (/). 

Description 

MASM  translates  assembly-language  source  code  into  relocatable  object  modules.  The 
object  modules  can  then  be  placed  in  a  library  file  or  processed  by  the  Microsoft  Object 
Linker  (LINK)  to  create  an  executable  program. 

The  source^file  parameter  is  the  only  required  filename.  It  specifies  a  file  containing 
the  assembly-language  source  code  in  ASCII  text.  If  no  extension  is  specified,  MASM 
uses  .ASM.  If  no  source  file  is  entered  in  the  command  line,  MASM  prompts  for  a  source 
file  name. 

The  object ^file  parameter  specifies  the  file  that  will  contain  the  assembled  relocatable 
object  code.  If  this  parameter  is  not  supplied,  MASM  uses  the  same  filename  as 
source^file  but  substitutes  the  extension  .OBJ. 

The  list _f He  parameter  specifies  a  destination  file  or  device  for  the  optional  program 
listing.  The  listing  contains  the  original  source  code,  the  assembled  machine  code,  macro 
definitions  and  expansions,  and  other  useful  information,  formatted  into  pages  with  titles, 
dates,  and  page  numbers.  If  the  destination  of  the  listing  is  a  file,  the  file’s  default  exten¬ 
sion  is  .LST.  If  the  list^ file  parameter  is  not  included  in  the  command  line,  MASM  sends 
the  listing  to  NUL  (that  is,  a  listing  is  not  produced). 

The  cref_file  parameter  specifies  the  name  of  a  cross-reference  file  to  receive  information 
to  be  processed  by  the  CREF  utility.  If  a  file  extension  is  not  specified,  MASM  uses  .CRF.  If 
the  cref^file  parameter  is  not  included  in  the  command  line,  MASM  sends  the  file  to  NUL 
(that  is,  no  cross-reference  file  is  generated). 


1008  The  MS-DOS  Encyclopedia 


MASM 


If  the  MASM  command  is  entered  without  parameters,  MASM  prompts  the  user  for  each 
filename.  The  default  response  for  each  prompt  (except  the  source  file  prompt)  is  dis¬ 
played  in  square  brackets  and  can  be  selected  by  pressing  the  Enter  key. 

After  the  source  file  is  specified,  if  MASM  encounters  a  semicolon  character  (;)  in  the 
command  line  or  at  any  prompt,  it  uses  default  values  for  the  remaining  parameters.  MASM 
ignores  any  parameters  specified  after  the  semicolon. 

MASM  does  two  passes  to  translate  the  assembly-language  code  in  the  source  file  into 
relocatable  object  code.  Any  errors  detected  during  translation  are  displayed  on  standard 
output  and  included  in  the  program  listing  (if  one  is  requested).  Two  types  of  errors  may 
be  detected:  warning  errors  and  severe  errors.  If  MASM  encounters  a  warning  error,  it  still 
creates  the  object  file,  although  the  resulting  file  may  be  unusable.  If  MASM  encounters  a 
severe  error,  it  does  not  create  the  object  file.  After  a  file  has  been  successfully  assembled 
without  errors,  the  LINK  utility  can  be  used  to  convert  the  resulting  object  file  into  an 
executable  program  file. 

MASM  supports  a  wide  variety  of  options  that  can  be  selected  by  including  switches  in  the 
command  line  or  by  responding  to  any  prompt. 

The  A  and  /S  switches  determine  the  order  of  segments  in  the  resulting  object  module 
file.  The  A  switch  places  the  segments  into  the  object  file  in  alphabetic  order.  The  /S 
switch  (the  default)  arranges  the  segments  in  the  same  order  they  occur  in  the  source  file. 

The  /Bn,  /^symbol,  and  /Ipath  switches  have  rather  general  effects  on  the  behavior  of 
MASM.  The  /Bn  switch  sets  the  size  (in  kilobytes)  of  the  source  file’s  RAM  buffer;  the 
value  of  n  must  be  between  1  and  63,  inclusive  (default  =  32).  If  the  RAM  buffer  is  large 
enough,  the  entire  source  file  can  be  kept  resident  in  memory,  reducing  disk  activity  dur¬ 
ing  passes.  The  /Dsymbol  switch  defines  a  null  text-string  symbol  from  the  command 
line.  This  symbol  can  be  referenced  inside  the  program  with  the  IFDEF  directive  to  con¬ 
trol  the  conditional  assembly  of  portions  of  the  program.  The  /Ipath  switch  specifies  a 
directory  that  will  be  searched  for  files  named  in  assembler  INCLUDE  statements  if  those 
statements  do  not  include  an  explicit  directory.  As  many  as  10  such  search  paths  can  be 
specified  with  individual  /Ipath  switches. 

The  /E  and  /R  switches  affect  the  generation  of  code  for  the  8087/80287  emulator  or 
8087/80287  math  coprocessor.  (Support  for  the  80287  is  included  with  MASM  versions  3.0 
and  later.)  The  /E  switch  generates  software  interrupts  to  floating-point-processor  emula¬ 
tor  routines.  A  subprogram  assembled  with  the  /E  switch  can  be  linked  to  C,  Pascal,  and 
FORTRAN  programs  and  can  use  the  emulator  libraries.  The  /R  switch  produces  in-line 
machine  instructions  for  the  math  coprocessor  when  floating-point  mnemonics  are  used. 

The  /ML,  /MU,  and  /MX  switches  control  MASM’s  handling  of  uppercase  and  lowercase 
names.  The  /ML  switch  makes  MASM  case  sensitive;  that  is,  it  makes  MASM  differentiate  a 
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name  in  uppercase  letters  from  the  same  name  in  lowercase  letters.  (The  /ML  switch 
should  not  be  used  if  the  source  file  contains  8087  WA.IT  instructions  and  MASM  4.0  is 
being  used  to  translate  the  file.)  The  /MU  switch  (the  default)  makes  MASM  case  insensi¬ 
tive;  all  lowercase  letters  are  converted  to  uppercase  for  purposes  of  assembly.  The  /MX 
switch  makes  MASM  case  sensitive  for  public  and  external  names  only  (names  defined 
with  PUBLIC  or  EXTRN  directives).  The  /MX  switch  is  often  used  to  process  assembly- 
language  functions  for  C  programs. 

The  /P  switch  checks  for  impure  code  segments  that  will  cause  problems  if  the  assembled 
program  is  run  in  80286  protected  mode.  The  switch  checks  by  flagging  any  instruction 
that  will  change  a  memory  location  addressed  through  the  processor’s  CS  register.  The  /P 
switch  has  no  effect  unless  the  assembly-language  source  file  includes  the  .286P  directive. 

The  /C,  /D,  /L,  /N,  and  /X  switches  control  the  contents  of  the  program  listing  and  other 
optional  files  that  are  generated  as  a  result  of  assembly.  The  /C  switch  causes  the  creation 
of  a  cross-reference  (.CRF)  file  and  the  addition  of  line  numbers  to  the  list  (.LST)  file  (if 
one  exists).  The  /C  switch  should  be  included  in  the  command  line  if  the  cross-reference 
file  will  be  used  later  with  the  CREF  utility  to  produce  a  cross-reference  listing.  The  /D 
switch  includes  a  listing  from  the  first  pass  as  well  as  a  listing  from  the  second  pass  in  the 
list  file  if  a  list  file  was  specified  (default  =  second-pass  listing  only).  By  comparing  the  two 
listings,  the  user  can  isolate  an  instruction  causing  a  phase  error.  (A  phase  error  occurs 
when  MASM  makes  assumptions  about  addresses,  values,  or  data  types  on  the  first  pass 
that  are  not  valid  in  the  second  pass.)  The  /L  switch  creates  a  list  file  with  line-number  in¬ 
formation  and  gives  it  the  same  name  as  the  source  file,  with  the  extension  .LST.  The  /N 
switch  suppresses  generation  of  tables — symbols,  segments,  groups,  structures,  records, 
and  macros — at  the  end  of  a  program  listing.  The  /X  switch  includes  statements  inside 
false  conditional  statements  in  the  list  file,  allowing  conditionals  that  do  not  generate  code 
to  be  displayed.  /X  has  no  effect  if  the  .SECOND  or  the  .LFCOND  directive  is  used  in  the 
source  file;  if  the  .TFCOND  directive  is  used,  the  effects  of  /X  are  reversed. 

Note:  The  effects  of  /X  are  also  reversed  in  MASM  version  1.2.  In  that  version,  statements 
within  a  false  conditional  are  included  in  the  list  file  by  default,  and  /X  will  suppress  them. 

The  /T,  /V,  and  /Z  switches  affect  MASM’s  display  on  standard  output.  The  /T  (terse) 
switch  suppresses  messages  to  standard  output,  except  for  messages  indicating  warning 
errors  or  severe  errors.  The  /V  (verbose)  switch  displays  information  about  the  number  of 
source  lines  and  symbols  at  the  end  of  the  assembly,  in  addition  to  displaying  the  normal 
error  and  symbol  space  information.  The  /Z  switch  displays  the  actual  source  lines  pro¬ 
ducing  assembly  errors  (rather  than  displaying  just  the  error  type  and  line  number). 
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Note:  Versions  of  MASM  earlier  than  4.0  always  show  both  the  source  line  and  the  error 
message. 

Return  Codes 

0  No  errors  were  found  during  assembly. 

1  An  error  was  detected  in  one  of  the  command-line  parameters. 

2  The  assembly-language  source  file  could  not  be  opened. 

3  The  list  file  could  not  be  created. 

4  The  object  file  could  not  be  created. 

5  The  cross-reference  file  could  not  be  created. 

6  An  include  file  could  not  be  opened. 

7  At  least  one  severe  error  was  detected  during  assembly.  (MASM  deletes  the  invalid 
object  file.) 

8  The  assembly  was  terminated  because  a  memory  allocation  error  occurred. 

10  An  error  occurred  in  defining  a  symbol  (with  the  /Dsymbol  switch)  from  the 
command  line. 

1 1  Assembly  was  interrupted  by  the  user’s  pressing  Ctrl-C  or  Ctrl-Break. 

Examples 

To  assemble  the  source  file  CLEAN. ASM  in  the  current  drive  and  directory  and  place  the 
resulting  relocatable  object  module  in  the  file  CLEAN.OBJ  without  producing  a  listing  or  a 
cross-reference  file,  type 

C>MASM  CLEAN;  <Enter> 

The  semicolon  after  the  first  parameter  causes  MASM  to  use  the  default  values  for  the  rest 
of  the  parameters. 

To  assemble  the  source  file  CLEAN.ASM,  put  the  object  code  in  a  file  named  CLEAN.OBJ, 
create  a  list  file  named  CLEAN.LST,  and  place  information  for  later  processing  by  the  CREF 
utility  in  the  cross-reference  file  CLEAN.CRF,  type 

C>MASM  CLEAN, CLEAN, CLEAN, CLEAN  <Enter> 

or 

C>MASM  CLEAN, , CLEAN, CLEAN  <Enter> 

To  use  MASM  interactively,  enter  its  name  without  parameters: 

C>MASM  <Enter> 

MASM  then  prompts  for  all  the  necessary  information.  For  example,  the  interactive  session 
on  the  next  page  assembles  the  file  HELLO.ASM  into  the  file  HELLO.OBJ,  producing  no 
listing  or  .CRF  file. 
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OMASM  <Enter> 

Microsoft  (R)  Macro  Assembler  Version  4.00 

Copyright  (C)  Microsoft  Corp  1981,  1983,  1984,  1985.  All  rights  reserved. 

Source  filename:  [.ASM]:  HELLO  <Enter> 

Object  filename:  [HELLO. OBJ] :  <Enter> 

Source  listing  [NUL.LST] :  <Enter> 

Cross-reference  [NUL.CRF] :  <Enter> 

51004  Bytes  symbol  space  free 

0  Warning  Errors 
0  Severe  Errors 

Messages 

8087  opcode  can’t  be  emulated 

An  8087  opcode  or  the  operands  used  with  it  produced  an  instruction  the  emulator  cannot 
support. 

Already  defined  locally 

An  attempt  was  made  to  define  a  symbol  as  EXTRN  that  had  already  been  defined  locally. 

Already  had  ELSE  clause 

An  attempt  was  made  to  define  an  ELSE  clause  within  an  existing  ELSE  clause.  (ELSE  can¬ 
not  be  nested  without  nesting  IF . . .  ENDIF.) 

Already  have  base  register 

More  than  one  base  register  was  specified  within  an  operand. 

Already  have  index  register 

More  than  one  index  register  was  specified  within  an  operand. 

Block  nesting  error 

A  segment,  structure,  macro,  IRC,  IRP,  KEPT,  or  nested  procedure  was  not  terminated 
properly. 

Byte  register  is  illegal 

A  byte  register  was  used  incorrectly  in  an  instruction. 

Can’t  override  ES  segment 

An  attempt  was  made  to  override  the  ES  segment  in  an  instruction  in  which  this  override  is 
invalid. 

Can’t  reach  with  segment  reg 

No  ASSUME  directive  was  given  to  make  the  variable  reachable. 

Can’t  use  EVEN  on  BYTE  segment 

An  EVEN  directive  was  used  on  a  segment  declared  to  be  a  byte  segment. 

Circular  chain  of  EQU  aliases 

An  alias  EQU  ultimately  points  to  itself. 
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Constant  was  expected 

A  constant  was  expected,  but  an  item  was  received  that  does  not  evaluate  to  a  constant. 

CS  register  illegal  usage 

The  CS  register  was  used  incorrectly  in  one  of  the  instructions. 

Data  emitted  with  no  segment 

Code  that  is  not  located  within  a  segment  attempted  to  generate  data. 

Directive  illegal  in  STRUC 

All  statements  within  STRUC  blocks  must  be  either  comments  preceded  by  a  semicolon 
character  (;)  or  one  of  the  define  directives  (DB,  DW,  and  so  on). 

Division  by  0  or  overflow 

An  expression  was  encountered  that  resulted  in  either  a  division  by  0  or  a  number  too 
large  to  be  represented. 

DUP  is  too  large  for  linker 

Nesting  of  DUP  operators  was  such  that  a  record  too  large  for  LINK  was  created. 

End  of  file,  no  END  directive 

No  END  statement  was  encountered,  or  a  nesting  error  occurred. 

Extra  characters  on  line 

Superfluous  characters  were  detected  on  a  line  after  sufficient  information  to  define  an 
instruction  was  interpreted. 

extra  file  name  ignored 

The  command  line  contained  more  than  four  filename  parameters. 

Field  cannot  be  overridden 

An  attempt  was  made  to  give  a  value  to  a  field  that  cannot  be  overridden  with  a  STRUC 
initialization  statement. 

Forced  error 

An  error  was  forced  with  the  .ERR  directive. 

Forced  error  -  expression  equals  0 

An  error  was  forced  with  the  .ERRE  directive. 

Forced  error  -  expression  not  equal  0 

An  error  was  forced  with  the  .ERRNZ  directive. 

Forced  error  -  passl 

An  error  was  forced  with  the  .ERRl  directive. 

Forced  error  -  pass2 

An  error  was  forced  with  the  .ERR2  directive. 

Forced  error  -  string  blank 

An  error  was  forced  with  the  .ERRB  directive. 
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Forced  error  -  string  not  blank 

An  error  was  forced  with  the  .ERRNB  directive. 

Forced  error  -  strings  different 

An  error  was  forced  with  the  .ERRDIF  directive. 

Forced  error  -  strings  identical 

An  error  was  forced  with  the  .ERRIDN  directive. 

Forced  error  -  symbol  defined 

An  error  was  forced  with  the  .ERRDEF  directive. 

Forced  error  -  symbol  not  defined 

An  error  was  forced  with  the  .ERRNDEF  directive. 

Forward  reference  is  illegal 

An  item  was  referenced  in  the  operand  of  an  EQU  or  equal-sign  (=)  directive  before  it  was 
defined. 

Illegal  register  value 

A  specified  register  value  does  not  fit  into  the  reg  field  (that  is,  the  value  is  greater  than  7). 

Illegal  size  for  item 

The  size  of  the  referenced  item  is  invalid.  This  error  also  frequently  occurs  when  an 
attempt  is  made  to  assemble  source  code  written  for  assemblers  with  less  strict  type¬ 
checking  than  that  of  the  Microsoft  Macro  Assembler  (such  as  early  versions  of  the  IBM 
assembler).  The  problem  can  usually  be  solved  by  overriding  the  type  of  the  operand  with 
the  PTR  operator. 

Illegal  use  of  external 

A  variable  that  was  declared  external  was  used  incorrectly. 

Illegal  use  of  register 

An  attempt  was  made  to  use  a  register  with  an  instruction  in  which  a  register  cannot  be 
used. 

Illegal  value  for  DUP  count 

The  DUP  count  was  not  a  constant  that  evaluates  to  a  positive  integer  greater  than  zero. 

Improper  operand  type 

An  operand  was  used  in  a  way  that  prevents  opcode  generation. 

Improper  use  of  segment  register 

An  attempt  was  made  to  use  a  segment  register  in  an  instruction  in  which  use  of  a  segment 
register  is  not  permitted. 

Impure  memory  reference 

An  attempt  was  made  to  store  data  in  the  code  segment  when  the  .286P  directive  and  the 
/P  switch  were  in  effect. 
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Index  dispL  must  be  constant 

An  index  displacement  was  used  incorrectly  or  did  not  evaluate  to  an  absolute  number  or 
memory  address. 

Internal  error 

An  internal  logic  error  was  detected  in  the  assembler.  Etocument  the  circumstances  and 
contact  Microsoft  Corporation. 

Label  can’t  have  seg.  override 

A  segment  override  was  used  incorrectly. 

Left  operand  must  have  segment 

The  content  of  the  right  operand  requires  that  a  segment  be  specified  in  the  left  operand. 

line  too  long  expanding  symbol 

A  symbol  defined  by  an  EQU  or  equal-sign  (=)  directive  is  so  long  that  expanding  it  will 
cause  the  assembler’s  internal  buffers  to  overflow.  This  message  may  indicate  a  recursive 
text  macro. 

Missing  data;  zero  assumed 

An  operand  is  missing  from  a  statement  and  MASM  assumes  its  value  is  zero.  This  is  a 
warning  error;  the  object  file  is  not  deleted  as  it  is  with  severe  errors. 

More  values  than  defined  with 

Too  many  initial  values  were  given  when  defining  a  variable  using  a  REC  or  STRUC  type. 

Must  be  associated  with  code 

A  data-related  item  was  used  where  a  code-related  item  was  expected. 

Must  be  associated  with  data 

A  code-related  item  was  used  where  a  data-related  item  was  expected. 

Must  be  AX  or  AL 

A  register  other  than  AX  or  AL  was  specified  where  only  these  are  acceptable. 

Must  be  in  segment  block 

An  attempt  was  made  to  generate  code  by  instructions  that  were  not  contained  within  a 
segment. 

Must  be  index  or  base  register 

An  instruction  requires  a  base  or  index  register,  and  some  other  register  was  specified 
within  square  brackets  ([]). 

Must  be  record  field  name 

A  record  field  name  was  expected,  but  something  else  was  encountered. 

Must  be  record  or  fieldname 

A  record  name  or  field  name  was  expected,  but  something  else  was  encountered. 

Must  be  register 

A  register  was  expected  as  the  operand,  but  something  else  was  encountered. 
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Must  be  segment  or  group 

A  segment  or  group  was  expected,  but  something  else  was  encountered. 

Must  be  structure  field  name 

A  structure  field  name  was  expected,  but  something  else  was  encountered. 

Must  be  symbol  type 

A  BYTE,  WORD,  DWORD,  or  similar  designation  was  expected,  but  something  else  was 
encountered. 

Mustbe  var,  label  or  constant 

A  variable,  label,  or  constant  was  expected,  but  something  else  was  encountered. 

Must  have  opcode  after  prefix 

A  REP,  REPE,  REPNE,  REPZ,  or  REPNZ  instruction  was  not  followed  by  the  mnemonic  for  a 
string  operation. 

Near  JMP/CALL  to  different  CS 

An  attempt  was  made  to  do  a  NEAR  jump  or  call  to  a  location  in  a  code  segment  defined 
with  a  different  ASSUMEiCS. 

No  immediate  mode 

Immediate  data  was  supplied  as  an  operand  for  an  instruction  that  cannot  use  immediate 
data.  For  example,  immediate  data  cannot  be  moved  directly  with  a  MOV  instruction  to  a 
segment  register;  it  must  first  be  moved  into  a  general  register  and  then  copied  to  the  seg¬ 
ment  register. 

No  or  unreachable  CS 

An  attempt  was  made  to  jump  to  a  label  that  is  unreachable. 

Normal  type  operand  expected 

A  STRUG,  BYTE,  WORD,  or  some  other  invalid  operand  was  encountered  when  a  variable 
label  was  expected. 

Not  in  conditional  block 

An  ENDIF  or  ELSE  statement  was  encountered,  and  no  previous  conditional-assembly 
directive  was  active. 

Not  proper  align/combine  type 

The  SEGMENT  parameters  are  incorrect.  Check  the  align  and  combine  types  to  be  sure 
they  are  valid. 

One  operand  must  be  const 

The  addition  operator  was  used  incorrectly. 

Only  initialize  list  legal 

An  attempt  was  made  to  use  a  STRUG  name  without  angle  brackets  (<>). 

Operand  combination  illegal 

A  two-operand  instruction  was  specified  and  the  combination  specified  was  invalid. 
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Operand  must  have  segment 

A  SEG  directive  was  used  incorrectly. 

Operand  must  have  size 

An  operand  was  encountered  that  needed  a  specified  size,  but  none  had  been  provided. 
Often  this  error  can  be  remedied  by  using  the  PTR  operator  to  specify  a  size  type. 

Operand  not  in  IP  segment 

An  operand  cannot  be  accessed  because  it  is  not  in  the  segment  last  assigned  to  CS  with  an 
ASSUME  directive. 

Operand  types  must  match 

MASM  encountered  different  kinds  or  sizes  of  arguments  in  a  case  where  they  must  match. 

Operand  was  expected 

MASM  expected  an  operand,  but  an  operator  was  encountered. 

Operands  must  be  same  or  1  abs 

The  subtraction  operator  was  used  incorrectly. 

Operator  was  expected 

MASM  expected  an  operator,  but  an  operand  was  encountered. 

Out  of  memory 

System  memory  is  insufficient  to  complete  the  assembly.  If  a  listing  (.LST)  or  cross- 
reference  (.CRF)  file  was  being  generated,  retry  the  assembly,  generating  only  an  object 
file.  It  may  also  be  necessary  to  modify  the  source  program  to  reduce  the  load  on  the  sym¬ 
bol  table  (by  shortening  names  or  reducing  the  number  of  EQU  statements  or  macros,  for 
example). 

Override  is  of  wrong  type 

An  attempt  was  made  to  use  a  data  item  of  incorrect  size  in  a  STRUG  initialization 
statement. 

Override  value  is  wrong  length 

The  override  value  for  a  structure  field  is  too  large  to  fit  in  the  field. 

Override  with  DUP  is  illegal 

An  attempt  was  made  to  use  DUP  to  override  in  a  STRUG  initialization  statement. 

Phase  error  between  passes 

The  program  has  ambiguous  instruction  directives  that  caused  the  location  of  a  label  in 
the  program  to  change  in  value  between  the  first  and  second  passes  of  MASM.  A  common 
cause  is  a  forward  reference  to  a  typed  data  item  in  the  instructions  preceding  the  label 
that  generated  the  phase  error  message.  Use  the  /D  switch  to  produce  a  first-pass  listing 
to  aid  in  resolving  phase  errors  between  passes. 

Redefinition  of  symbol 

This  message  is  displayed  during  first  pass  upon  the  second  declaration  of  a  symbol  that 
has  been  defined  in  more  than  one  place. 
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Reference  to  mult  defined 

The  instruction  references  a  symbol  that  has  been  defined  more  than  once. 

Register  already  defined 

An  internal  error  was  detected.  Note  the  circumstances  of  the  failure  and  contact  Microsoft 
Corporation. 

Relative  jump  out  of  range 

A  conditional  jump  references  a  label  that  is  out  of  the  allowed  range  of -128  to  +127  bytes 
relative  to  the  current  instruction.  The  problem  usually  can  be  corrected  by  reversing  the 
condition  of  the  jump  and  using  an  unconditional  jump  (JMP)  to  the  out-of-range  label. 

Segment  parameters  are  changed 

The  list  of  parameters  encountered  for  a  SEGMENT  was  not  identical  to  the  list  specified 
the  first  time  the  segment  was  used. 

Shift  count  is  negative 

A  shift  expression  was  generated  that  resulted  in  a  negative  shift  count. 

Should  have  been  group  name 

A  group  name  was  expected,  but  something  else  was  encountered. 

Symbol  already  different  kind 

An  attempt  was  made  to  redefine  an  already  defined  symbol. 

Symbol  has  no  segment 

An  attempt  was  made  to  use  a  variable  with  SEG  that  has  no  known  segment. 

Symbol  is  already  external 

An  attempt  was  made  to  redefine  a  symbol  as  local  that  has  already  been  defined  as 
external. 

Symbol  is  multi-defined 

This  message  is  displayed  during  the  second  pass  upon  each  declaration  of  a  symbol  that 
has  been  defined  in  more  than  one  place. 

Symbol  is  reserved  word 

An  attempt  was  made  to  use  a  reserved  MASM  word  as  a  symbol. 

Symbol  not  defined 

A  symbol  that  had  not  been  defined  was  used. 

Symbol  type  usage  illegal 

A  PUBLIC  symbol  was  used  incorrectly. 

Syntax  error 

The  syntax  of  the  statement  does  not  match  any  recognizable  syntax. 

Type  illegal  in  context 

The  type  specified  is  of  an  unacceptable  size. 


1018  The  MS-DOS  Encyclopedia 


MASM 


Unable  to  open  input  file  filename 

The  specified  source  file  cannot  be  found. 

unknown  switch  letter 

The  command  line  included  an  invalid  switch. 

Unknown  symbol  type 

MASM  does  not  recognize  the  size  type  specified  in  a  label  or  external  declaration.  Rewrite 
with  a  valid  type  such  as  BYTE,  WORD,  or  NEAR. 

Value  is  out  of  range 

A  value  is  too  large  for  its  expected  use. 

Wrong  type  of  register 

A  directive  or  instruction  expected  one  type  of  register,  but  another  type  was 
encountered. 
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Program  Debugger 


Purpose 

Allows  the  controlled  execution  of  a  program  for  debugging  purposes  or  the  alteration  of 
the  binary  contents  of  any  file.  The  DEBUG  utility  is  supplied  with  the  MS-DOS  distribu¬ 
tion  disks. 

Syntax 

DEBUG 

or 

DEBUG  fUename  [ parameter . . .  ] 
where: 

filename  is  the  name  of  the  file  that  contains  data  to  be  modified  or  a  program  to  be 

debugged.  If  filename  includes  an  extension,  it  must  be  specified. 
parameter ...  is  one  or  more  filenames  or  switches  required  by  a  program  being 
debugged. 

Description 

The  DEBUG  program  allows  a  file  to  be  loaded,  examined,  and  altered.  If  the  file  is  not  a 
.EXE  file  or  a  .HEX  file,  it  may  also  be  written  back  to  disk.  If  the  file  contains  a  program, 
the  program  can  be  disassembled,  modified,  traced  one  instruction  at  a  time,  or  executed 
at  full  speed  with  preset  breakpoints.  DEBUG  can  also  be  used  to  read  from  and  write  to 
input/output  (I/O)  ports  and  to  read,  modify,  and  write  absolute  disk  sectors. 

The  command  line  typically  includes  the  filename  parameter,  which  is  the  name  of  an 
executable  program  (with  the  extension  .COM  or  .EXE)  to  be  loaded  into  DEBUG’s  mem¬ 
ory  buffer.  Files  with  the  extension  .EXE  are  loaded  in  a  manner  compatible  with  the 
MS-DOS  loader;  if  necessary,  the  contents  of  the  file  are  relocated  so  that  the  program  is 
ready  to  execute.  Files  with  the  extension  .HEX  are  converted  to  binary  images  and  loaded 
at  the  internally  specified  address.  All  other  files  are  assumed  to  be  direct  memory  images 
and  are  read  directly  into  memory  starting  at  offset  lOOH. 

An  appropriate  program  segment  prefix  (PSP)  is  synthesized  at  the  head  of  DEBUG’s 
buffer  for  use  by  the  target  program  (the  program  being  debugged).  The  PSP  includes  a 
command  tail  at  offset  80H  and  default  file  control  blocks  (FCBs)  at  offsets  5CH  and  6CH, 
constructed  from  the  optional  parameters  following  filename. 

After  DEBUG  is  loaded  and  the  first  file  named  in  the  command  line  is  also  located  and 
loaded,  DEBUG  displays  its  special  prompt  character,  a  hyphen  (-),  and  awaits  a  com¬ 
mand.  DEBUG  commands  consist  of  a  single  letter,  usually  followed  by  one  or  more 
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parameters.  Uppercase  and  lowercase  characters  are  treated  the  same  except  when  they 
are  contained  in  strings  enclosed  within  single  or  double  quotation  marks.  All  commands 
are  executed  by  pressing  the  Enter  key. 

The  DEBUG  commands  are 


Command  Action 


A 

C 

D 

E 

F 

G 

H 

I 

L 

M 

N 

O 

P 

Q 

R 

S 

T 

U 

W 


Assemble  machine  instructions  (versions  2.0  and  later). 
Compare  memory  areas. 

Display  memory. 

Enter  data. 

Fill  memory. 

Go  execute  program. 

Perform  hexadecimal  arithmetic. 

Input  from  port. 

Load  file  or  sectors. 

Move  (copy)  data. 

Name  file  or  command-tail  parameters. 

Output  to  port. 

Proceed  through  loop  or  subroutine  (versions  3.0  and  later). 
Quit  debugger. 

Display  or  modify  registers. 

Search  memory. 

Trace  program  execution. 

Disassemble  (unassemble)  program. 

Write  file  or  sectors. 


The  parameters  for  a  DEBUG  command  include  addresses,  ranges,  8-bit  or  l6-bit  hexa¬ 
decimal  values,  and  lists.  Multiple  parameters  can  be  separated  by  spaces,  tabs,  or 
commas,  but  separators  are  required  only  between  hexadecimal  values. 

An  address  can  be  a  simple  offset  or  a  complete  address  in  the  form  segment  .offset.  The 
offset  is  always  a  hexadecimal  number  in  the  range  OOH  through  FFFFH;  the  segment  can 
be  either  a  hexadecimal  value  in  the  same  range  or  a  two-character  segment  register  name 
(CS,  DS,  ES,  or  SS).  If  the  segment  portion  of  an  address  is  absent,  DEBUG  uses  DS  unless 
an  A,  G,  L,  T,  U,  or  W  command  is  used,  in  which  case  DEBUG  uses  CS. 

A  range  specifies  an  area  of  memory  and  can  be  expressed  as  either  two  addresses  or  a 
starting  address  and  a  length.  A  segment  can  be  included  only  in  the  first  element  of  a 
range;  an  error  message  is  displayed  if  a  segment  is  found  in  the  second  address.  A  length  is 
represented  by  the  letter  L,  followed  by  a  hexadecimal  value  between  OOH  and  FFFFH  that 
indicates  the  number  of  bytes  following  the  starting  address  that  the  command  should 
operate  on. 

Note:  Any  length  that  causes  an  address  to  exceed  l6  bits  will  generate  an  error. 

A  byte,  or  8-bit,  value  is  entered  as  one  or  two  hexadecimal  digits,  whereas  a  word,  or 
l6-bit,  value  is  entered  as  one  to  four  hexadecimal  digits.  Leading  zeros  can  be  omitted. 
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A  list  is  composed  of  one  or  more  byte  values  or  strings,  separated  by  spaces,  commas,  or 
tabs.  A  string  is  one  or  more  ASCII  characters  enclosed  within  single  or  double  quotation 
marks.  Case  is  significant  within  a  string.  If  the  same  type  of  quote  character  that  is  used  to 
delimit  the  string  occurs  inside  the  string  itself,  the  character  must  be  doubled  inside  the 
string  in  order  to  be  interpreted  correctly.  For  example: 

"This  ""string""  is  OK." 

When  used,  a  list  must  be  the  last  parameter  in  the  command  line. 

DEBUG  responds  to  an  invalid  command  by  pointing  to  the  approximate  location  of  the 
error  with  a  caret  character  (^)  and  displaying  the  word  Error.  For  example: 

-D  CS:0100,CS:0200  <Enter> 

Error 

DEBUG  maintains  a  set  of  virtual  CPU  registers  for  a  program  being  debugged.  These 
registers  can  be  examined  and  modified  with  DEBUG  commands.  When  a  program  is  first 
loaded  for  debugging,  the  virtual  registers  are  initialized  with  the  following  values: 


Register 

.COM  Program 

.EXE  Program 

AX 

Valid  drive  error  code 

Valid  drive  error  code 

BX 

Upper  half  of  program  size 

Upper  half  of  program  size 

CX 

Lower  half  of  program  size 

Lower  half  of  program  size 

DX 

Zero 

Zero 

SI 

Zero 

Zero 

DI 

Zero 

Zero 

BP 

Zero 

Zero 

SP 

FFFEH  or  top  of  available 

Size  of  stack  segment 

memory  minus  2 

IP 

lOOH 

Offset  of  entry  point  within  target 

program’s  code  segment 

CS 

PSP 

Base  of  target  program’s  code  segment 

DS 

PSP 

PSP 

ES 

PSP 

PSP 

ss 

PSP 

Base  of  target  program’s  stack  segment 

Note:  DEBUG  checks  the  first  three  parameters  in  the  command  line.  If  the  second  and 
third  parameters  are  filenames,  DEBUG  checks  any  drive  specifications  with  those  file¬ 
names  to  verify  that  they  designate  valid  drives.  Register  AX  contains  one  of  the  following 

codes: 

Code 

Meaning 

OOOOH  The  drives  specified  with  the  second  and  third  filenames  are  both  valid,  or 
only  one  filename  was  specified  in  the  command  line. 

OOFFH  The  drive  specified  with  the  second  filename  is  invalid. 

FFOOH  The  drive  specified  with  the  third  filename  is  invalid. 

FFFFH  The  drives  specified  with  the  second  and  third  filenames  are  both  invalid. 
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DEBUG  also  maintains  a  set  of  virtual  flags,  which  may  be  set  or  cleared.  The  flags  are 


Flag  Name 

Value  If  Set  (1) 

Value  If  Clear  (0) 

Overflow 

OV  (Overflow) 

NV  (No  Overflow) 

Direction 

DN  (Down) 

UP  (Up) 

Interrupt 

El  (Enabled) 

DI  (Disabled) 

Sign 

NG  (Minus) 

PL  (Plus) 

Zero 

ZR  (Zero) 

NZ  (Not  Zero) 

Aux  Carry 

AC  (Aux  Carry) 

NA  (No  Aux  Carry) 

Parity 

PE  (Even) 

PO(Odd) 

Carry 

CY  (Carry) 

NC  (No  Carry) 

Before  DEBUG  transfers  control  to  the  target  program,  it  saves  the  actual  CPU  registers  and 
then  loads  them  with  the  current  values  of  the  virtual  registers.  Conversely,  when  control 
reverts  to  DEBUG  from  the  target  program,  the  returned  register  contents  are  stored  back 
in  the  virtual  register  set  for  inspection  and  alteration  by  the  user. 

Examples 

To  load  the  file  SHELL.EXE  in  the  current  directory  for  execution  under  the  control  of 
DEBUG,  type 

C> DEBUG  SHELL.EXE  <Enter> 

To  use  the  DEBUG  program  to  inspect  or  modify  memory  or  to  read,  modify,  and  write 
absolute  disk  sectors,  simply  type 

C> DEBUG  <Enter> 

Message 

File  not  found 

The  filename  supplied  as  the  first  parameter  in  the  DEBUG  command  line  cannot  be 
found. 
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Assemble  Machine  Instructions 


Purpose 

Allows  entry  of  assembler  mnemonics  and  translates  them  into  executable  machine  code. 

Syntax 

K[address] 

where: 

address  is  the  starting  location  for  the  assembled  machine  code. 

Description 

The  Assemble  Machine  Instructions  (A)  command  accepts  assembly-language  statements, 
rather  than  hexadecimal  values,  for  the  Intel  8086/8088  microprocessors  and  the  Intel  8087 
math  coprocessor  and  then  assembles  each  statement  into  executable  machine  code. 

The  address  parameter  specifies  the  location  where  entry  of  assembly-language 
mnemonics  will  begin.  If  address  is  omitted,  DEBUG  uses  the  address  following  the  last 
instruction  generated  the  last  time  the  A  command  was  used.  If  the  A  command  has  not 
been  used,  DEBUG  uses  the  current  value  of  the  target  program’s  CS:IP  registers. 

After  an  A  command  is  entered,  DEBUG  prompts  for  each  assembly-language  statement 
by  displaying  the  address,  in  the  form  of  a  segment  and  an  offset,  in  which  the  assembled 
code  will  be  stored.  When  the  Enter  key  is  pressed,  the  assembly-language  statement  is 
translated,  and  each  byte  of  the  resulting  machine  instruction  is  stored  sequentially  in 
memory  (overwriting  existing  information),  beginning  at  the  displayed  address.  The  ad¬ 
dress  following  the  last  byte  of  the  machine  instruction  is  then  displayed  so  that  the  user 
can  enter  the  next  assembly-language  statement.  Pressing  the  Enter  key  alone  in  response 
to  the  address  prompt  terminates  the  A  command. 

The  syntax  of  assembly-language  statements  accepted  by  the  DEBUG  A  command  differs 
slightly  from  that  of  the  usual  Microsoft  Macro  Assembler  programming  statements.  The 
differences  can  be  summarized  as  follows: 

•  All  numbers  are  assumed  to  be  hexadecimal  integers  and  should  be  entered  without  a 
trailing  H  character. 

•  Segment  overrides  must  be  specified  by  preceding  the  entire  instruction  with  CS:, 

DS:,  ES:,  or  SS:. 

•  File  control  directives  (NAME,  PAGE,  TITLE,  and  so  forth),  macro  definitions,  record 
structures,  and  conditional  assembly  directives  are  not  supported  by  DEBUG. 

•  Specific  hexadecimal  values,  rather  than  program  labels,  must  be  included. 
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•  When  the  data  type  (word  or  byte)  is  not  implicit  in  the  instruction,  the  type  must  be 
specified  by  preceding  the  operand  with  BYTE  PTR  (or  BY)  or  WORD  PTR  (or  WO). 

•  The  size  of  the  string  in  a  string  operation  must  be  specified  by  adding  a  B  (byte)  or 
W  (word)  to  the  string  instruction  mnemonic  (for  example,  LODSB  or  LODSW). 

•  The  DB  and  DW  instructions  accept  a  parameter  of  the  type  list  and  assemble  byte 
and  word  values  directly. 

•  The  WAIT  or  FWAIT  opcodes  for  8087  assembler  statements  are  not  generated  by 
default,  so  they  must  be  coded  explicitly. 

•  Memory  locations  are  differentiated  from  immediate  operands  by  enclosing  memory 
addresses  in  square  brackets. 

•  Repeat  prefixes,  such  as  REP,  REP2,  or  REPNZ,  can  be  entered  either  alone  on  the  line 
preceding  the  statement  they  affect  or  immediately  preceding  the  statement  on  the 
same  line. 

•  Although  the  assembler  generates  the  optimal  form  (SHORT,  NEAR,  or  FAR)  for  jumps 
or  calls,  depending  on  the  destination  address,  these  designations  can  be  overridden 
by  preceding  the  operand  with  a  NEAR  (or  NE)  or  FAR  (no  abbreviation)  prefix. 

•  The  mnemonic  for  a  EAR  RETURN  is  RETF. 

Examples 

To  begin  assembling  code  at  address  CS:0100H,  type 

-A  100  <Enter> 

To  assemble  the  instruction  sequence 

LCDS  WORD  PTR  [SI] 

XCHG  BX,AX 
JMP  [BX] 

beginning  at  address  CSiOlOOH,  the  following  dialogue  would  take  place: 

-A  1 00  <Enter> 

1983:0100  LODSW  <Enter> 

1983:0101  XCHG  BX,AX  <Enter> 

1983:0103  JMP  [BX]  <Enter> 

1983:0105  <Enter> 

To  continue  assembling  at  the  location  following  the  last  instruction  generated  by  a  pre¬ 
vious  A  command,  type 

-A  <Enter> 
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DEBUG:  C 

Compare  Memory  Areas 


Purpose 

Compares  two  areas  of  memory  and  reports  any  differences. 

Syntax 

C  range  address 
where: 

range  is  the  starting  and  ending  ad[dresses  or  the  starting  address  and  length  of  the 
first  area  of  memory  to  be  compared. 

address  is  the  starting  address  of  the  second  area  of  memory  to  be  compared. 

Description 

The  Compare  Memory  Areas  (C)  command  compares  the  contents  of  two  areas  of  mem¬ 
ory.  The  location  and  contents  of  any  differing  bytes  are  displayed  in  the  following  format: 

addressl  bytel  byte2  address2 

If  no  differences  are  found,  the  DEBUG  prompt  returns. 

The  range  parameter  specifies  the  starting  and  ending  addresses  or  the  starting  address 
and  length  in  bytes  of  the  first  area  of  memory  to  be  compared.  The  address  parameter 
specifies  the  beginning  address  of  the  second  area  of  memory  to  be  compared.  If  a 
segment  is  not  included  in  range  or  address^  DEBUG  uses  DS. 

Example 

To  compare  the  64  bytes  beginning  at  CS:CE00H  with  the  64  bytes  beginning  at 
CS:CF0AH,  type 

-C  CS:CE00  CE3F  CSrCFOA  <Enter> 

or 

-C  CSrCEOO  L40  CS:CF0A  <Enter> 

If  any  differences  are  found,  DEBUG  displays  them  in  the  following  format: 

2124:CE06  00  FF  2124:CF10 
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DEBUG:  D 

Display  Memory 


Purpose 

Displays  the  contents  of  an  area  of  memory  in  hexadecimal  and  ASCII  format. 

Syntax 

D  [range] 
where: 

range  is  the  starting  and  ending  addresses  or  the  starting  address  and  length  of  the 

area  to  be  displayed. 

Description 

The  Display  Memory  (D),  or  Dump,  command  displays  the  contents  of  a  specified  range  of 
memory  addresses  in  hexadecimal  and  ASCII  format. 

The  range  parameter  gives  the  starting  and  ending  addresses  or  the  starting  address  and 
length  in  bytes  of  the  memory  to  be  displayed.  If  range  does  not  include  a  segment, 
DEBUG  uses  DS. 

If  range  is  omitted  the  first  time  the  D  command  is  used,  the  display  starts  at  the  target 
program’s  CS.IP  registers.  If  range  was  specified  in  a  preceding  D  command,  the  memory 
address  following  the  last  address  displayed  by  that  command  is  used.  If  a  length  is  not  ex¬ 
plicitly  stated  in  a  D  command,  128  bytes  are  displayed. 

Each  line  displays  a  segment  and  offset,  followed  by  the  contents  of  16  bytes  of  memory 
represented  as  hexadecimal  values  and  separated  by  spaces  (except  the  eighth  and  ninth 
values,  which  are  separated  by  a  dash),  followed  by  the  ASCII  character  equivalents  (if 
any)  of  the  same  16  bytes.  In  the  ASCII  portion,  nonprinting  characters  are  displayed  as 
periods. 

Examples 

To  display  the  contents  of  the  128  bytes  of  memory  beginning  at  7F00:0100H,  type 


-D  7F00:0100  <Enter> 

The  contents  of  the  memory  addresses  are  displayed  in  the  following  format: 


7F00:0100 

20 

64 

65 

76 

69 

63 

65 

OD-OA 

00 

60 

39 

OD 

OA 

00 

7C 

device. . . ' 9 . . . I 

7FOO:O110 

39 

08 

20 

08 

00 

81 

39 

04-1B 

5B 

32 

4A 

42 

BD 

11 

44 

9.  . . .9. . [2JB=.D 

7F00:0120 

2E 

26 

45 

AF 

11 

47 

B3 

11-48 

A5 

11 

4C 

B8 

11 

4E 

D3 

.&E/.G3.H%.L8.NS 

7F00:0130 

11 

50 

DF 

11 

51 

AB 

11 

54-DF 

IE 

56 

37 

11 

5F 

9F 

16 

.P_.Q+.T_.V7 _ 

7F00:0140 

24 

CO 

11 

00 

03 

4E 

4F 

54-C1 

07 

OA 

45 

52 

52 

4F 

52 

$@. . .NOTA. .ERROR 

7FOO:O150 

4C 

45 

56 

45 

4C 

85 

08 

05-45 

58 

49 

53 

54 

18 

08 

00 

LEVEL. . .EXIST. . . 

7F00:0160 

03 

44 

49 

52 

03 

91 

oc 

06-52 

45 

4E 

41 

4D 

45 

01 

CO 

.DIR _ RENAME.  @ 

7F00:0170 

OF 

03 

52 

45 

4E 

01 

CO 

OF-05 

45 

52 

41 

53 

45 

01 

68 

. .REN.@. . ERASE. h 
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To  view  the  next  128  bytes  of  memory,  type 

-D  <Enter> 

In  this  case,  the  contents  of  memory  addresses  7F00:0180H  through  7F00:01FFH  are 
displayed. 
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DEBUG:  E 

Enter  Data 


Purpose 

Enters  data  into  memory. 

Syntax 

E  address  [list] 
where: 

address  is  the  first  memory  location  for  data  entry. 

list  specifies  the  data  to  be  entered  into  successive  bytes  of  memory,  starting  at 

address. 

Description 

The  Enter  Data  (E)  command  allows  data  to  be  entered  into  successive  memory  locations. 
The  data  can  be  entered  in  either  hexadecimal  or  ASCII  format.  Data  previously  stored  in 
the  specified  locations  is  lost. 

The  address  parameter  specifies  the  first  byte  to  be  modified.  If  address  does  not  include 
a  segment,  DEBUG  uses  DS.  The  address  is  incremented  for  each  byte  of  data  stored. 

The  list  parameter  is  one  or  more  hexadecimal  byte  values  and/or  strings,  separated  by 
spaces,  commas,  or  tab  characters.  Strings  must  be  enclosed  within  single  or  double  quota¬ 
tion  marks,  and  case  is  significant  within  a  string. 

If  list  is  included  in  the  command  line,  the  changes  to  memory  are  made  unless  an  error  is 
detected  in  the  command  line,  in  which  case  an  error  message  is  displayed  and  the  E  com¬ 
mand  is  terminated.  If  list  is  omitted  from  the  command  line,  the  user  is  prompted  byte 
by  byte  for  data  to  be  entered  into  memory,  starting  at  address.  The  current  contents  of  a 
byte  are  displayed,  followed  by  a  period.  A  new  value  for  that  byte  can  be  entered  as  one 
or  two  hexadecimal  digits  (extra  characters  are  ignored)  or  the  contents  can  be  left  un¬ 
changed.  Pressing  the  spacebar  displays  the  contents  of  the  next  byte.  Entering  a  minus 
sign  or  hyphen  character  (-)  instead  of  pressing  the  spacebar  displays  the  contents  of  the 
previous  byte.  A  maximum  of  8  bytes  can  be  entered  on  each  input  line;  a  new  line  is 
begun  each  time  an  8-byte  boundary  is  crossed.  Pressing  the  Enter  key  without  pressing 
the  spacebar  or  entering  any  data  terminates  data  entry. 

Text  strings  can  be  entered  only  by  using  the  list  parameter;  they  cannot  be  entered  in 
response  to  an  address  prompt. 
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Examples 

To  store  the  byte  values  OOH,  ODH,  and  OAH  in  the  three  bytes  beginning  at  DS:1FB3H, 
type 

-E  1FB3  00  OD  OA  <Enter> 

To  store  the  string  MAIN  MENU  into  memory  beginning  at  address  ES:0Cl4H,  type 

-E  ES:C14  "MAIN  MENU"  <Enter> 
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DEBUG:  F 

Fill  Memory 


Purpose 

Stores  a  repetitive  data  pattern  in  an  area  of  memory. 

Syntax 

F  range  list 
where: 

range  is  the  starting  and  ending  addresses  or  starting  address  and  length  of  the  mem¬ 
ory  to  be  filled. 

list  is  the  data  to  be  entered. 

Description 

The  Fill  Memory  (F)  command  fills  an  area  of  memory  with  the  data  from  a  list.  The  data 
can  be  entered  in  either  hexadecimal  or  ASCII  format.  Any  data  previously  stored  at  the 
specified  locations  is  lost.  If  an  error  message  is  displayed,  the  original  values  in  memory 
remain  unchanged. 

The  range  parameter  specifies  the  starting  and  ending  addresses  or  the  starting  address 
and  hexadecimal  length  in  bytes  of  the  area  of  memory  to  be  filled.  If  range  does  not 
specify  a  segment,  DEBUG  uses  DS. 

The  list  parameter  specifies  one  or  more  hexadecimal  byte  values  and/or  strings,  sepa¬ 
rated  by  spaces,  commas,  or  tab  characters.  Strings  must  be  enclosed  in  single  or  double 
quotation  marks,  and  case  is  significant  within  a  string. 

If  the  area  to  be  filled  is  larger  than  the  data  list,  the  list  is  repeated  as  often  as  necessary  to 
fill  the  area.  If  the  data  list  is  longer  than  the  area  of  memory  to  be  filled,  it  is  truncated  to 
fit  into  the  area. 

Examples 

To  fill  the  area  of  memory  from  DS:0B10H  through  DS:0B4FH  with  the  value  0E8H,  type 

-F  BIO  B4F  E8  <Enter> 

or 

-F  BIO  L40  E8  <Enter> 
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To  fill  the  16  bytes  of  memory  beginning  at  address  CSilFAOH  by  replicating  the  2-byte 
sequence  ODH  OAH,  type 

-F  CSrIFAO  1FAF  OD  OA  <Enter> 

or 

-F  CStIFAO  L10  OD  OA  <Enter> 

To  fill  the  area  of  memory  from  ESiOBOOH  through  ES:0BFFH  by  replicating  the  text  string 
BUFFER,  type 

-F  ES:B00  BFF  "BUFFER”  <Enter> 

or 

-F  ES:B00  LI  00  "BUFFER"  <Enter> 
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Purpose 

Transfers  control  from  DEBUG  to  the  program  being  debugged. 

Syntax 

G  [=address]  [breakO  [...  break9]] 
where: 

address  is  the  location  DEBUG  begins  execution. 

breaW. . .  break9  specify  from  1  to  10  temporary  breakpoints. 

Description 

The  Go  (G)  command  transfers  control  from  DEBUG  to  the  program  being  debugged.  If 
no  breakpoints  are  set,  the  program  executes  until  it  crashes  or  finishes,  in  which  latter 
case  the  message  Program  terminated  normally  is  displayed  and  control  returns  to 
DEBUG.  (After  this  message  is  displayed,  the  program  may  need  to  be  reloaded  before  it 
can  be  executed  again.) 

The  address  parameter  can  specify  any  location  in  memory.  If  no  segment  is  specified, 
DEBUG  uses  the  target  program’s  CS  register.  If  address  is  omitted,  DEBUG  transfers  to 
the  current  address  in  the  target  program’s  CS:IP  registers.  An  equal  sign  (=)  must  precede 
address  to  distinguish  it  from  the  breakpoints  breakO. . .  break9. 

The  parameters  breakO. . .  break9  are  addresses  that  represent  from  1  to  10  temporary 
breakpoints  that  can  be  set  as  part  of  the  G  command.  A  breakpoint  is  an  address  at  which 
execution  stops.  Breakpoints  can  be  placed  in  any  order,  because  execution  stops  at  the 
first  breakpoint  address  encountered,  regardless  of  the  position  of  that  breakpoint  in  the 
list.  Each  breakpoint  address  must  contain  the  first  byte  of  an  8086  opcode.  DEBUG  in¬ 
stalls  breakpoints  by  replacing  the  first  byte  of  the  machine  instruction  at  each  breakpoint 
address  with  an  INT  03H  instruction  (opcode  OCCH).  If  the  program  encounters  a  break¬ 
point,  execution  is  suspended  and  control  returns  to  DEBUG.  DEBUG  then  restores  the 
original  machine  code  to  the  breakpoint  addresses;  displays  the  contents  of  the  registers, 
the  status  of  the  flags,  and  the  instruction  pointed  to  by  CS:IP;  and  displays  the  DEBUG 
prompt.  If  the  program  executes  to  completion  without  encountering  any  of  the  break¬ 
points  or  stops  for  any  reason  other  than  because  it  encountered  a  breakpoint,  DEBUG 
does  not  replace  the  INT  03H  instructions  with  the  original  machine  code,  and  the  Load 
File  or  Sectors  (L)  command  must  be  used  to  reload  the  original  program. 

The  G  command  requires  that  the  target  program’s  SS:SP  registers  point  to  a  valid  stack 
that  has  at  least  6  bytes  of  stack  space  available.  When  the  G  command  is  executed,  it 
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pushes  the  target  program’s  flags  and  CS  and  IP  registers  onto  the  stack  and  then  transfers 
control  to  the  target  program  with  an  IRET  instruction.  Thus,  if  the  target  program’s  stack 
is  not  valid  or  is  too  small,  the  system  may  crash. 

Examples 

To  begin  execution  of  the  program  in  DEBUG’s  buffer  at  location  CSdlOAH  and  set  break¬ 
points  at  CS:12FCH  and  CS:1303H,  type 

-G  =11 OA  12FC  1303  <Enter> 

To  resume  execution  of  the  program  after  a  breakpoint  has  been  encountered  and  control 
has  been  returned  to  DEBUG,  type 

-G  <Enter> 

Messages 

bp  Error 

More  than  10  breakpoints  were  specified  in  a  G  command.  The  command  must  be  entered 
again  with  10  or  fewer  breakpoints. 

Program  terminated  normally 

No  breakpoints  were  encountered  and  the  target  program  executed  to  completion.  If 
breakpoints  were  set,  the  original  program  should  be  restored  with  the  L  command. 
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DEBUG:  H 

Perform  Hexadecimal  Arithmetic 

Purpose 

Displays  the  sum  and  difference  of  two  hexadecimal  numbers. 

Syntax 

H  valuel  value2 
where: 

valuel  and  value2  are  any  two  hexadecimal  numbers  from  0  through  FFFFH. 

Description 

The  Perform  Hexad^imal  Arithmetic  (H)  command  displays  the  sum  and  the  difference 
of  two  l6-bit  hexadecimal  numbers — that  is,  the  result  of  the  operations  valuel^value2 
and  valuel~value2.  If  valt4e2  is  greater  than  valuel,  the  difference  of  the  two  values  is  dis¬ 
played  as  a  two’s  complement  number.  This  command  is  convenient  for  quickly  calculat¬ 
ing  addresses  and  other  values  during  an  interactive  debugging  session. 

Examples 

To  display  the  sum  and  the  difference  of  the  values  4B03H  and  104H,  type 

-H  4B03  104  <Enter> 

This  produces  the  following  display: 

4C07  49FF 

If  the  addition  produces  an  overflow,  the  four  least  significant  digits  are  displayed.  For 
example,  the  command  line 

-H  FFFF  2  <Enter> 

produces  the  following  display: 

0001  FFFD 

If  the  second  number  is  bigger  than  the  first,  the  difference  is  displayed  in  two’s  comple¬ 
ment  form.  For  example,  the  command  line 

-H  1  2  <Enter> 

produces  the  following  display: 

0003  FFFF 
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Input  from  Port 


Purpose 

Reads  and  displays  1  byte  from  an  input/output  (I/O)  port. 

Syntax 

I  port 
where: 

port  is  an  I/O  port  address  from  0  through  FFFFH. 

Description 

The  Input  from  Port  (I)  command  reads  the  specified  I/O  port  address  and  displays  the 
data  as  a  two-digit  hexadecimal  number. 

Warning:  The  I  command  should  be  used  with  caution  because  it  directly  accesses  the 
computer  hardware  and  no  error  checking  is  performed.  Input  operations  directed  to  the 
ports  assigned  to  some  peripheral  device  controllers  may  interfere  with  the  proper  opera¬ 
tion  of  the  system.  If  no  device  has  been  assigned  to  the  specified  I/O  port  or  if  the  port  is 
write-only,  the  value  displayed  by  an  I  command  is  unreliable. 

Example 

To  read  and  display  the  contents  of  I/O  port  lOAH,  type 

-I  10A  <Enter> 

An  example  of  the  output  of  this  command  is 

FF 
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Load  File  or  Sectors 


Purpose 

Loads  a  file  or  individual  sectors  from  a  disk  into  DEBUG’s  memory. 

Syntax 

L  [address] 
or 

L  address  drive  start  number 
where: 

address  is  the  memory  location  for  the  data  to  be  read  from  the  disk. 

drive  is  the  number  of  the  disk  drive  to  read  (0  =  drive  A,  1  =  drive  B,  2  =  drive  C, 

and  so  on). 

start  is  the  hexadecimal  number  of  the  first  logical  sector  to  load  (0~FFFFH). 

number  is  the  hexadecimal  number  of  consecutive  sectors  to  load  (0-FFFFH). 

Description 

The  Load  File  or  Sectors  (L)  command  loads  a  file  or  individual  sectors  from  a  disk.  When 
the  L  command  is  entered  without  parameters  or  with  only  an  address,  the  file  specified  in 
the  DEBUG  command  line  or  the  one  in  the  most  recent  Name  File  or  Command-Tail 
Parameters  (N)  command  line  is  loaded  from  the  disk  into  memory.  If  no  segment  is  speci¬ 
fied  in  address,  DEBUG  uses  CS.  If  the  file’s  extension  is  .EXE,  the  file  is  placed  in 
DEBUG’s  target  program  buffer  at  the  load  address  specified  in  the  .EXE  file’s  header.  If 
the  file’s  extension  is  .COM,  the  file  is  loaded  at  offset  lOOH.  (If  for  some  reason  an  address 
other  than  lOOH  is  entered  for  a  .EXE  or  .COM  file,  an  error  message  is  displayed;  if  the  ad¬ 
dress  is  lOOH,  the  specification  is  ignored.)  The  length  of  the  file  or,  in  the  case  of  a  .EXE 
file,  the  actual  length  of  the  program  (the  length  of  the  file  minus  the  header)  is  placed  in 
the  target  program’s  BX  and  CX  registers,  with  the  most  significant  16  bits  in  register  BX. 

The  L  command  can  also  be  used  to  bypass  the  MS-DOS  file  system  and  directly  access 
logical  sectors  on  the  disk.  The  memory  address  iaddres^,  disk  drive  number  idriv^, 
starting  logical  sector  number  (start),  and  number  of  sectors  to  load  (number)  must  all  be 
specified  in  the  command  line. 

Note:  The  L  command  should  not  be  used  to  access  logical  sectors  on  network  drives. 

Examples 

To  load  the  file  specified  in  the  DEBUG  command  line  or  in  the  most  recent  N  command 
into  DEBUG’s  target  program  buffer,  type 

-L  <Enter> 
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To  load  eight  sectors  from  drive  B,  starting  at  logical  sector  0,  to  memory  location 
CSiOlOOH,  type 

-L  100  1  08  <Enter> 

Messages 

Disk  error  reading  drive  JT 

The  specified  drive  does  not  exist  or  the  disk  in  the  specified  drive  is  defective. 

File  not  found 

The  file  specified  in  the  most  recent  N  command  cannot  be  found. 
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Move  (Copy)  Data 


Purpose 

Copies  the  contents  of  one  area  of  memory  to  another. 

Syntax 

M  range  address 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  of  memory  to  be  copied. 
address  is  the  first  byte  in  which  the  copied  data  will  be  placed. 

Description 

The  Move  (Copy)  Data  (M)  command  copies  data  from  one  memory  location  to  another 
without  altering  the  data  in  the  original  location.  If  the  source  and  destination  areas  over¬ 
lap,  the  data  is  copied  so  that  the  resulting  copy  is  correct;  the  data  in  the  original  location 
is  changed  where  the  two  areas  overlap. 

The  range  parameter  specifies  either  the  starting  and  ending  addresses  or  the  starting 
address  and  length  of  the  memory  to  be  copied.  The  address  parameter  is  the  first  byte  in 
which  the  copy  will  be  placed.  If  range  does  not  contain  an  explicit  segment,  DEBUG  uses 
DS;  if  address  does  not  contain  a  segment,  DEBUG  uses  the  segment  used  for  range. 

Example 

To  copy  the  data  in  locations  DS:0800H  through  DS:08FFH  to  locations  DS:0900H  through 
DS:09FFH,  type 

-M  800  8FF  900  <Enter> 

or 

-M  800  LI  00  900  <Enter> 
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Name  File  or  Command-Tail  Parameters 


Purpose 

Inserts  filenames  and/or  switches  into  the  simulated  program  segment  prefix  (PSP). 

Syntax 

N parameter  [parameter. 
where: 

parameter  is  one  or  more  filenames  or  switches  to  be  placed  in  the  simulated  PSP. 

Description 

The  Name  File  or  Command-Tail  Parameters  (N)  command  is  used  to  enter  one  or  more 
parameters  into  the  simulated  PSP  that  is  built  at  the  base  of  the  buffer  holding  the  pro¬ 
gram  to  be  debugged.  The  N  command  can  also  be  used  before  the  Load  File  or  Sectors  (L) 
and  Write  File  or  Sectors  (W)  commands  to  name  the  file  to  be  read  from  or  written  to  a 
disk. 

The  count  of  the  characters  following  the  N  command  is  placed  at  DS:0080H  in  the  simu¬ 
lated  PSP,  and  the  characters  themselves  are  copied  into  the  PSP  starting  at  offset  81H.  The 
string  is  terminated  by  a  carriage  return  (ODH),  which  is  not  included  in  the  count.  If  the 
first  and  second  parameters  follow  the  naming  conventions  for  MS-DOS  files,  they  are 
parsed  into  the  default  file  control  blocks  (FCBs)  in  the  simulated  PSP  at  offsets  5CH  and 
6CH,  respectively.  (Switches  specified  as  parameters  are  stored  in  the  PSP  starting  at  offset 
81H  along  with  the  rest  of  the  command  line  but  are  not  included  in  the  FCBs.) 

If  the  N  command  line  contains  only  one  filename,  any  parameters  placed  in  the  default 
FCBs  by  a  previous  N  command  are  destroyed.  If  the  drive  specified  with  the  first  filename 
parameter  is  invalid,  the  AL  register  is  set  to  OFFH.  If  the  drive  specified  with  the  second 
filename  parameter  is  invalid,  the  AH  register  is  set  to  OFFH.  The  existence  of  a  file  speci¬ 
fied  with  the  N  command  is  not  verified  until  it  is  loaded  with  the  L  command. 

Examples 

Assume  that  DEBUG  was  started  without  specifying  the  name  of  a  target  program  in  the 
command  line.  To  load  the  program  CLEAN.COM  for  execution  under  the  control  of 
DEBUG,  use  the  N  and  L  commands  together  as  follows: 

-N  CLEAN.COM  <Enter> 

-L  <Enter> 

Then,  to  place  the  parameter  MYFILE.DAT  in  the  simulated  PSP’s  command  tail  and 
parse  MYFILE.DAT  into  the  first  default  FCB,  type 

-N  MYFILE.DAT  <Enter> 
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Finally,  to  execute  the  program  CLEAN.COM,  type 

-G  <Enter> 

The  result  is  the  same  as  if  the  CLEAN.COM  program  had  been  run  from  the  MS-DOS 
command  level  with  the  entry 

C>CLEAN  MYFILE.DAT  <Enter> 

except  that  the  program  is  executing  under  the  control  of  DEBUG  and  within  DEBUG’s 
memory  buffer. 
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Output  to  Port 


Purpose 

Writes  1  byte  to  an  input/output  (I/O)  port. 

Syntax 

O  port  byte 
where: 

port  is  an  I/O  port  address  from  0  through  FFFFH. 

f^te  is  a  value  from  0  through  OFFH  to  be  written  to  the  I/O  port. 

Description 

The  Output  to  Port  (O)  command  writes  1  byte  of  data  to  the  specified  I/O  port  address. 
The  data  value  must  be  in  the  range  OOH  through  OFFH. 

Warning:  The  O  command  should  be  used  with  caution  because  it  directly  accesses  the 
computer  hardware  and  no  error  checking  is  performed.  Attempts  to  write  to  some  port 
addresses,  such  as  those  for  ports  connected  to  peripheral  device  controllers,  timers,  or  the 
system’s  interrupt  controller,  may  cause  the  system  to  crash  or  damage  data  stored  on  disk. 

Example 

To  write  the  value  C8H  to  I/O  port  lOAH,  type 

-0  10A  C8  <Enter> 
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Proceed  Through  Loop  or  Subroutine 


Purpose 

Executes  a  loop,  repeated  string  instruction,  software  interrupt,  or  subroutine  call 
to  completion. 

Syntax 

P  [= address]  [number] 
where: 

address  is  the  location  of  the  first  instruction  to  be  executed. 

number  is  the  number  of  instructions  to  execute. 

Description 

The  Proceed  Through  Loop  or  Subroutine  (P)  command  transfers  control  from  DEBUG 
to  the  target  program.  The  program  executes  without  interruption  until  the  loop,  repeated 
string  instruction,  software  interrupt,  or  subroutine  call  at  address  is  completed  or  until 
the  specified  number  of  machine  instructions  have  been  executed.  Control  then  returns 
to  DEBUG,  and  the  contents  of  the  target  program's  registers  and  the  status  of  the  flags  are 
displayed. 

If  the  address  parameter  does  not  include  an  explicit  segment,  DEBUG  uses  the  target  pro¬ 
gram’s  CS  register;  if  address  is  omitted  entirely,  execution  begins  at  the  address  specified 
by  the  target’s  CS:IP  registers.  The  address  parameter  must  be  preceded  by  an  equal  sign 
(=)  to  distinguish  it  from  number. 

If  the  instruction  at  address  is  not  a  loop,  repeated  string  instruction,  software  interrupt, 
or  subroutine  call,  the  P  command  functions  just  like  the  Trace  Program  Execution  (T) 
command.  The  optional  number  parameter  specifies  the  number  of  instructions  to  be 
executed  before  control  returns  to  DEBUG.  If  number  is  omitted,  DEBUG  executes  only 
one  instruction.  After  each  instruction  is  executed,  DEBUG  displays  the  contents  of  the 
target  program’s  registers,  the  status  of  the  flags,  and  the  next  instruction  to  be  executed. 

Warning:  The  P  command  cannot  be  used  to  trace  through  ROM. 

Example 

Assume  that  the  target  program’s  location  CS:143FH  contains  a  CALL  instruction.  To 
execute  the  subroutine  that  is  the  destination  of  CALL  and  then  return  control  to 
DEBUG,  type 

-P  =143F  <Enter> 
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Quit 

Purpose 

Ends  a  DEBUG  session. 

Syntax 

Q 

Description 

The  Quit  (Q)  command  terminates  the  DEBUG  program  and  returns  control  to  MS-DOS  or 
the  command  shell  that  invoked  DEBUG.  Any  changes  to  a  program  or  other  file  that  were 
not  saved  on  disk  with  the  Write  File  or  Sectors  (W)  command  are  lost. 

Example 

To  exit  DEBUG,  type 

-Q  <Enter> 
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Display  or  Modify  Registers 


Purpose 

Displays  the  contents  of  one  or  all  registers  and  the  status  of  the  CPU  flags  and  allows 
them  to  be  modified. 

Syntax 

R  [register] 
where: 

register  is  the  two-character  name  of  an  Intel  8086/8088  register  from  the  following 
list: 

AX  BX  CX  DX  SP  BP  SI  DI 
DS  ES  SS  CS  IP  PC 

or  the  character  F,  which  specifies  the  CPU  flags. 

Description 

The  Display  or  Modify  Registers  (R)  command  displays  the  target  program’s  register  con¬ 
tents  and  the  status  of  the  CPU  flags  and  allows  them  to  be  modified. 

If  R  is  entered  without  a  register  parameter,  the  contents  of  all  registers  and  the  status  of 
the  CPU  flags  are  displayed,  followed  by  a  disassembly  of  the  machine  instruction  cur¬ 
rently  pointed  to  by  the  target  program’s  CS:IP  registers. 

If  register  is  included  in  the  R  command  line,  the  contents  of  the  specified  register  are  dis¬ 
played;  then  DEBUG  prompts  with  a  colon  character  (:)  for  a  new  value.  The  value  is  en¬ 
tered  by  typing  one  to  four  hexadecimal  digits  and  then  pressing  the  Enter  key.  Pressing 
the  Enter  key  without  entering  any  values  leaves  the  register  contents  unchanged. 

Note:  The  register  name  PC  is  not  fully  supported  in  some  versions  of  DEBUG,  so  the 
register  name  IP  should  be  used  instead. 

Specifying  the  character  F  instead  of  a  register  name  causes  DEBUG  to  display  the  status  of 
the  program’s  CPU  flags  as  two-character  codes  from  the  following  list: 


FlagName  ValuelfSet(l)  Value  If  Clear  (0) 


Overflow 

Direction 

Interrupt 


OV  (Overflow)  NV  (No  Overflow) 

DN  (Down)  UP  (Up) 

El  (Enabled)  DI  (Disabled) 


(more) 
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Flag  Name  Value  If  Set  (1)  Value  If  Clear  (0) 


Sign 

Zero 

Aux  Cany 

Parity 

Carry 


NG  (Minus) 

ZR  (Zero) 

AC  (Aux  Carry) 
PE  (Even) 

CY  (Carry) 


PL  (Plus) 

NZ  (Not  Zero) 

NA  (No  Aux  Carry) 
PO  (Odd) 

NC  (No  Carry) 


After  displaying  the  f  lag  values,  DEBUG  displays  a  hyphen  (-)  prompt  on  the  same  line. 
Any  or  all  flags  can  then  be  altered  by  typing  one  or  more  codes  (in  any  order  and  op¬ 
tionally  separated  by  spaces)  from  the  list  above  and  pressing  the  Enter  key.  Pressing  the 
Enter  key  without  entering  any  codes  leaves  the  status  of  the  flags  unchanged. 

Examples 

To  display  the  contents  of  the  target  program’s  CPU  registers  and  the  status  of  the  CPU 
flags,  followed  by  the  disassembled  mnemonic  for  the  next  instruction  to  be  executed 
(pointed  to  by  CS:IP),  type 

-R  <Enter> 

This  produces  a  display  in  the  following  format: 

AX=0000  BX=0000  CX=00A1  DX=0000  SP=FFFE  BP=0000  SI=0000  DI=0000 

DS=19A5  ES=19A5  SS=1 9A5  CS=1 9A5  IP=0100  NV  UP  El  PL  NZ  NA  PO  NC 

19A5:0100  BF8000  MOV  DI,0080 

To  display  the  value  of  the  target  program’s  BX  register,  type 

-R  BX  <Enter> 

If  BX  contains  0200H,  for  example,  DEBUG  displays  that  value  and  then  issues  a  prompt  in 
the  form  of  a  colon: 

BX  0200 


The  contents  of  BX  can  then  be  altered  by  typing  a  new  value  and  pressing  the  Enter  key 
or  left  unchanged  by  pressing  the  Enter  key  alone. 

To  set  the  direction  and  carry  flags,  first  type 

-R  F  <Enter> 

DEBUG  displays  the  flag  values,  followed  by  a  hyphen  (-)  prompt: 

NV  UP  El  PL  NZ  NA  PO  NC  - 

The  direction  and  carry  flags  can  then  be  set  by  entering 

-DN  CY  <Enter> 
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Messages 

bf  Error 

Bad  flag:  An  invalid  code  for  a  CPU  flag  was  entered. 

br  Error 

Bad  register:  An  invalid  register  name  was  entered. 

df  Error 

Double  flag:  Two  values  for  the  same  CPU  flag  were  entered  in  the  same  command. 
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Search  Memory 


Purpose 

Searches  memory  for  a  pattern  of  1  or  more  bytes. 

Syntax 

S  range  list 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  to  be  searched. 

list  is  1  or  more  consecutive  byte  values  and/or  a  string  to  be  searched  for. 

Description 

The  Search  Memory  (S)  command  searches  a  designated  range  of  memory  for  a  specified 
list  of  consecutive  byte  values  and/or  a  text  string.  The  starting  address  of  each  set  of 
matching  bytes  is  displayed.  The  contents  of  the  searched  area  are  not  altered. 

The  range  parameter  specifies  the  starting  and  ending  addresses  or  the  starting  address 
and  length  in  bytes  of  the  area  to  be  searched.  If  a  segment  is  not  included  in  range, 
DEBUG  uses  DS.  If  a  segment  is  specified  for  the  starting  address,  DEBUG  uses  the  same 
segment  for  the  ending  address.  If  a  starting  address  and  length  in  bytes  is  specified,  the 
starting  address  plus  the  length  minus  1  cannot  exceed  FFFFH. 

The  list  parameter  specifies  one  or  more  consecutive  hexadecimal  byte  values  and/or  a 
string  to  be  searched  for,  separated  by  spaces,  commas,  or  tab  characters.  Strings  must  be 
enclosed  within  single  or  double  quotation  marks,  and  case  is  significant  within  a  string. 

Examples 

To  search  for  the  string  Copyright  in  the  area  of  memory  from  DS:0000H  through 
DSilFFFH,  type 

“S  0  1FFF  'Copyright'  <Enter> 

or 

-S  0  L2000  "Copyright"  <Enter> 

If  matches  are  found,  DEBUG  displays  the  starting  address  of  each: 

20A8:0910 

20A8:094F 

20A8:097C 
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To  search  for  the  byte  sequence  3BH06H  in  the  area  of  memory  from  CS:0100H  through 
CS:12A0H,  type 

-S  CS:100  12A0  3B  06  <Enter> 

or 

-S  CS:100  L11A1  3B  06  <Enter> 
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Trace  Program  Execution 


Purpose 

Executes  one  or  more  instructions,  displaying  the  CPU  status  after  each  instruction. 

Syntax 

T  [= address]  [number] 
where: 

address  is  the  location  of  the  first  instruction  to  be  executed. 

number  is  the  number  of  machine  instructions  to  be  executed. 

Description 

The  Trace  Program  Execution  (T)  command  executes  one  or  more  instructions,  starting  at 
the  specified  address,  and  after  each  instruction  displays  the  contents  of  the  CPU  registers, 
the  status  of  the  flags,  and  the  instruction  pointed  to  by  CS:IP. 

Warning:  The  T  command  should  not  be  used  to  execute  any  instructions  that  change 
the  contents  of  the  Intel  8259  interrupt  mask  (ports  20H  and  21H  on  the  IBM  PC  and  com¬ 
patibles)  or  to  trace  calls  made  to  MS-DOS  through  Interrupt  21H.  The  Go  (G)  command 
should  be  used  instead. 

The  address  parameter  points  to  the  first  instruction  to  be  executed.  If  address  does  not 
include  a  segment,  DEBUG  uses  the  target  program’s  CS  register;  if  address  is  omitted  en¬ 
tirely,  execution  begins  at  the  address  specified  by  the  target  program’s  CS:IP  registers.  If 
address  is  included,  it  must  be  preceded  by  an  equal  sign  (=)  to  distinguish  it  from 
number 

The  number  parameter  specifies  the  hexadecimal  number  of  instructions  to  be  executed 
before  the  DEBUG  prompt  is  redisplayed  (default  =  1).  Pressing  Ctrl-C  or  Ctrl-Break  inter¬ 
rupts  execution  of  a  sequence  of  T  instructions.  Consecutive  instructions  can  then  be  exe¬ 
cuted  individually  by  entering  T  commands  with  no  parameters.  Pressing  Ctrl-S  suspends 
execution  and  pressing  any  key  then  resumes  the  trace. 

Note:  The  T  command  can  be  used  to  trace  through  ROM. 

Example 

To  execute  one  instruction  at  location  CS:1A00H  and  then  return  control  to  DEBUG,  dis¬ 
playing  the  contents  of  the  CPU  registers  and  the  status  of  the  flags,  type 

-T  =1A00  <Enter> 
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DEBUG:  U 

Disassemble  (Unassemble)  Program 


Purpose 

Disassembles  machine  instructions  into  assembly-language  mnemonics. 

Syntax 

U  [range] 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 

of  the  machine  code  to  be  disassembled. 

Description 

The  Disassemble  (Unassemble)  Program  (U)  command  translates  machine  instructions 
into  assembly-language  mnemonics. 

The  range  parameter  specifies  the  starting  and  ending  addresses  or  starting  address  and 
length  in  bytes  of  the  machine  instructions  to  be  disassembled.  If  range  does  not  specify  a 
segment,  DEBUG  uses  CS.  Note  that  if  the  starting  address  does  not  fall  on  an  8086  instruc¬ 
tion  boundary,  the  disassembly  will  be  incorrect. 

If  range  does  not  include  a  length  or  ending  address,  32  (20H)  bytes  of  memory  are  dis¬ 
assembled  beginning  at  the  specified  starting  address.  If  range  is  omitted,  32  bytes  of 
memory  are  disassembled,  starting  at  the  address  following  the  last  instruction  dis¬ 
assembled  by  the  previous  U  command.  If  a  U  command  has  not  been  used  before 
and  range  is  omitted,  disassembly  begins  at  the  address  specified  by  the  taiget 
program’s  CS:IP  registers. 

N<ae:  The  actual  number  of  bytes  displayed  may  vary  slightly  from  the  amount  specified 
in  range  or  from  the  default  of  32  bytes  because  the  length  of  instructions  may  vary.  Also, 
the  U  command  does  not  understand  instructions  specific  to  the  80186, 80286,  and  80386 
microprocessors.  It  displays  such  instructions  as  DBs. 

Successive  32-byte  fragments  of  code  can  be  disassembled  by  entering  additional  U  com¬ 
mands  without  parameters. 

Example 

To  disassemble  8  bytes  of  machine  instructions  starting  at  CS:0100H,  type 

-U  100  107  <Enter> 

or 

-U  1 00  L8  <Enter> 
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DEBUG;  W 

Write  File  or  Sectors 


Purpose 

Writes  a  file  or  individual  sectors  to  disk. 

Syntax 

W  [address] 
or 

W  address  drive  start  number 
where: 

address  is  the  first  memory  location  of  the  data  to  be  written. 

drive  is  the  number  of  the  destination  disk  drive  (0  =  drive  A,  1  =  drive  B,  2  =  drive 

C,  and  so  on). 

start  is  the  number  of  the  first  logical  sector  to  write  (0-FFFFH). 

number  is  the  number  of  consecutive  sectors  to  be  written  (0-FFFFH). 

Description 

The  Write  File  or  Sectors  (W)  command  transfers  a  file  or  individual  sectors  from  memory 
to  the  disk. 

When  the  W  command  is  entered  without  parameters  or  with  only  an  address,  the  number 
of  bytes  specified  by  the  contents  of  registers  BX:CX  is  written  from  memory  into  the  file 
named  in  the  most  recently  used  Name  File  or  Command-Tail  Parameters  (N)  command  or 
the  first  file  specified  in  the  DEBUG  command  line  if  the  N  command  has  not  been  used. 
Files  with  a  .EXE  or  .HEX  extension  cannot  be  written  with  the  DEBUG  W  command. 

Note:  If  a  Trace  Program  Execution  (T),  Go  (G),  or  Proceed  Through  Loop  or  Subroutine 
(P)  command  has  been  used  or  the  contents  of  the  BX  or  CX  registers  have  been  changed, 
the  contents  of  BXCX  must  be  restored  before  the  W  command  is  used. 

When  address  is  not  included  in  the  command  line,  the  target  program’s  CS:0100H  is 
assumed. 

The  W  command  can  also  be  used  to  bypass  the  MS-DOS  file  system  and  directly  access 
logical  sectors  on  the  disk.  The  memory  address  {.address),  disk  drive  number  {driv^, 
starting  logical  sector  number  {start),  and  number  of  sectors  to  be  written  {number)  must 
all  be  provided  in  the  command  line  in  hexadecimal  format.  The  W  command  should  not 
be  used  to  write  sectors  on  network  drives. 

Warning:  Extreme  caution  must  be  used  with  the  W  command.  The  disk’s  file  structure 
can  easily  be  damaged  if  the  wrong  parameters  are  entered. 
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Example 

Assume  that  the  interactive  Assemble  Machine  Instructions  (A)  command  was  used  to 
create  a  program  in  DEBUG’s  memory  buffer  that  is  32  (20H)  bytes  long,  beginning  at 
offset  OlOOH.  This  program  can  be  written  to  the  file  QUICK.COM  by  using  the  DEBUG 
Name  File  or  Command-Tail  Parameters  (N),  Display  or  Modify  Registers  (R),  and  Write 
File  or  Sectors  (W)  commands  sequentially.  First,  use  the  N  command  to  specify  the  name 
of  the  file  to  be  written: 

-N  QUICK.COM  <Enter> 

Next,  use  the  R  command  to  set  registers  BX  and  CX  to  the  length  to  be  written.  Register 
BX  contains  the  upper,  or  most  significant  half,  of  the  length,  whereas  register  CX  contains 
the  lower,  or  least  significant  half  Type 

-R  CX  <Enter> 

DEBUG  displays  the  contents  of  register  CX  and  prompts  with  a  colon  (:).  Enter  the 
length  after  the  prompt: 

:20  <Enter> 

To  use  the  R  command  again  to  set  register  BX  to  zero,  type 

-R  BX  <Enter> 

followed  by 

:0  <Enter> 

Finally,  to  create  the  disk  file  QUICK.COM  and  write  the  program  into  it,  type 

-W  <Enter> 

DEBUG  responds: 

Writing  0020  bytes 

Messages 

EXE  and  HEX  files  cannot  be  written 

Files  with  a  .EXE  or  .HEX  extension  cannot  be  written  to  disk  with  the  W  command. 

Writing  nnnn  bytes 

After  a  successful  write  operation,  DEBUG  displays  in  hexadecimal  format  the  number  of 
bytes  written  to  disk. 
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SYMDEB 

Symbolic  Debugger 


Purpose 

The  Symbolic  Debugger  (SYMDEB)  allows  a  file  to  be  loaded,  examined,  altered,  and  writ¬ 
ten  back  to  disk.  If  the  file  contains  a  program,  the  program  can  be  disassembled,  modi¬ 
fied,  traced  one  instruction  at  a  time,  or  executed  at  full  speed  with  breakpoints.  SYMDEB 
can  also  be  used  to  read,  modify,  and  write  absolute  disk  sectors. 

The  SYMDEB  utility  is  supplied  with  the  Microsoft  Macro  Assembler  (MASM)  versions  4.0 
and  earlier.  This  documentation  describes  SYMDEB  version  4.0. 


Syntax 

SYMDEB 


or 


SYMDEB  [  options]  [symfile  [symfile. . .  ]]  [filename  [ parameter. . .  ]] 
where: 


symfile 

filename 

parameter 

options 


is  the  name  of  a  symbol  file  created  with  the  MAPSYM  utility 
(extension  =  .SYM). 

is  the  name  of  the  binary  or  executable  program  file  to  be  debugged, 
is  a  command-line  parameter  required  by  the  program  being  debugged, 
is  one  or  more  of  the  following  switches.  Switches  can  be  either  upper¬ 
case  or  lowercase  and  can  be  preceded  by  a  dash  (-)  instead  of  a  forward 
slash  (/). 


/I 

/K 

/N 


/S 

/“commands” 


(IBM)  specifies  that  the  computer  is  IBM  compatible, 
enables  the  interactive  breakpoint  key  (Scroll  Lock), 
enables  the  use  of  nonmaskable  interrupt  break  sys¬ 
tems  on  IBM-compatible  computers  (requires  special 
hardware). 

enables  the  Screen  Swap  (\)  command  on  IBM-com¬ 
patible  computers  (the  /I  switch  is  also  required), 
specifies  one  or  more  SYMDEB  commands,  separated 
by  semicolons  and  enclosed  in  quotation  marks. 


Description 

The  SYMDEB  commands  and  capabilities  are  a  superset  of  those  in  DEBUG.  SYMDEB  is 
also  able  to  load  and  interpret  special  symbol  files  that  correlate  line  numbers,  symbols, 
and  memory  addresses.  With  the  aid  of  such  files,  SYMDEB  enables  the  user  to  specify 
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addresses  with  labels,  variable  names,  and  expressions,  rather  than  only  with  absolute 
hexadecimal  addresses.  SYMDEB’s  command  repertoire  also  includes  I/O  redirection 
commands,  floating-point  number  entry  and  display  commands,  and  source-code  display 
capabilities  that  are  not  present  in  DEBUG. 

The  SYMDEB  command  line  typically  includes  the  filename  parameter,  which  is  the 
name  of  an  executable  program  (with  the  extension  .COM  or  .EXE)  to  be  loaded  into 
SYMDEB’s  memory  buffer.  Files  with  the  extension  .EXE  are  loaded  in  a  manner  compat¬ 
ible  with  the  MS-DOS  loader.  Files  with  the  extension  .HEX  are  converted  to  binary  images 
and  loaded  at  the  internally  specified  address.  All  other  files  are  assumed  to  be  direct 
memory  images  and  are  read  directly  into  memory  starting  at  offset  lOOH.  If  SYMDEB  is 
entered  by  itself,  no  file  information  is  read  into  memory.  An  appropriate  program  seg¬ 
ment  prefix  (PSP)  is  synthesized  at  the  head  of  SYMDEB’s  buffer  for  use  by  the  target  pro¬ 
gram;  the  PSP  includes  a  command  tail  at  offset  80H  and  default  file  control  blocks  (FCBs) 
at  offsets  5CH  and  6CH,  constructed  from  the  optional  parameters  following  filename.  If 
necessary,  contents  of  the  file  are  relocated  so  that  the  file  is  ready  to  execute. 

The  command  line  can  also  contain  the  names  of  one  or  more  symfiles,  symbol  files  that 
contain  symbol  and  line-number  information  for  the  object  modules  that  constitute  the 
program  being  debugged.  A  symbol  file  is  created  with  the  MAPSYM  utility  from  a  map 
file  produced  by  the  Microsoft  Object  Linker  (LINK).  A  symbol  file  always  has  the  exten¬ 
sion  .SYM.  See  PROGRAMMING  UTILITIES:  mapsym;  link. 

The  four  command-line  switches  /I,  /K,  /N,  and  /S  provide  SYMDEB  with  information 
about  the  computer  on  which  the  utility  is  running.  The  /I  switch  is  used  when  the  com¬ 
puter  is  IBM  compatible;  this  causes  SYMDEB  to  take  full  advantage  of  special  hardware 
features  such  as  the  8259  Programmable  Interrupt  Controller  or  the  memory-mapped 
video  display.  The  /K  switch  enables  the  interactive  breakpoint  key  (Scroll  Lock),  which 
can  then  be  pressed  at  any  time  to  interrupt  a  program  that  is  being  traced  under  the  con¬ 
trol  of  SYMDEB. 

Note:  The  /K  switch  is  not  necessary  on  an  IBM  PCAT,  because  the  Sys  Req  key  is  always 
active  as  an  interactive  break  key. 

The  /N  switch  enables  the  use  of  the  nonmaskable  interrupt  as  a  breakpoint  signal  on 
IBM-corripatible  computers;  this  interrupt  is  triggered  by  hardware-assisted  debugging 
packages  such  as  Periscope  and  Atron  Corporation’s  Software  Probe.  The  /S  switch  en¬ 
ables  the  Screen  Swap  (\)  command,  which  allows  the  output  from  the  program  being 
traced  to  be  maintained  and  displayed  on  demand  on  a  virtual  screen  separate  from  the 
SYMDEB  commands  and  messages. 

Note:  The  /I,  /N,  and  /S  switches  are  unnecessary  on  personal  computers  built  by  IBM 
Corporation;  SYMDEB  automatically  enables  the  capabilities  provided  by  those  switches 
when  SYMDEB  finds  the  IBM  copyright  notice  in  the  machine’s  ROM. 

After  SYMDEB  and  any  files  named  in  the  command  line  are  loaded,  SYMDEB  displays  its 
special  prompt  character,  a  hyphen  (-),  and  awaits  a  command.  SYMDEB  commands  con¬ 
sist  of  one  or  two  letters,  usually  followed  by  one  or  more  parameters.  SYMDEB  treats 
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uppercase  and  lowercase  characters  equivalently  except  when  they  are  contained  in 
strings  enclosed  within  single  or  double  quotation  marks.  SYMDEB  does  not  execute 
commands  until  the  Enter  key  is  pressed. 

The  SYMDEB  commands  discussed  in  this  section  are 


Command  Action 


A 

BC 

BD 

BE 

BL 

BP 

C 

D 

DA 

DB 

DD 

DL 

DS 

DT 

DW 

E 

EA 

EB 

ED 

EL 

ES 

ET 

EW 

F 

G 

H 

I 

K 

L 

M 

N 

O 

P 

Q 

R 

S 


Assemble  machine  instructions. 

Clear  breakpoints. 

Disable  breakpoints. 

Enable  breakpoints. 

List  breakpoints. 

Set  breakpoints. 

Compare  memory  areas. 

Display  memory. 

Display  ASCII. 

Display  bytes. 

Display  doublewords. 

Display  long  reals. 

Display  short  reals. 

Display  10-byte  reals. 

Display  words. 

Enter  data. 

Enter  ASCII  string. 

Enter  bytes. 

Enter  doublewords. 

Enter  long  reals. 

Enter  short  reals. 

Enter  10-byte  reals. 

Enter  words. 

Fill  memory. 

Go  execute  program. 

Perform  hexadecimal  arithmetic. 

Input  from  port. 

Perform  stack  trace. 

Load  file  or  sectors. 

Move  (copy)  data. 

Name  file  or  command-tail  parameters. 
Output  to  port. 

Proceed  through  loop  or  subroutine. 
Quit  debugger. 

Display  or  modify  registers. 

Search  memory. 


(more) 
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Command  Action 

S+  Enable  source  display  mode. 

S-  Disable  source  display  mode. 

S&  Enable  source  and  machine  code  display  mode. 

T  Trace  program  execution. 

U  Disassemble  (unassemble)  program. 

V  View  source  code. 

W  Write  file  or  sectors. 

X  Examine  symbol  map. 

XO  Open  symbol  map. 

Z  Set  symbol  value. 

<  Redirect  SYMDEB  input. 

>  Redirect  SYMDEB  output. 

=  Redirect  SYMDEB  input  and  output. 

{  Redirect  target  program  input. 

}  Redirect  target  program  output. 

~  Redirect  target  program  input  and  output. 

\  Swap  screen. 

Display  source  line. 

?  Help  or  evaluate  expression. 

!  Escape  to  shell. 

♦  Enter  comment. 


One  or  more  SYMDEB  commands,  separated  by  semicolons  and  enclosed  in  double 
quotation  marks,  can  be  included  in  the  original  SYMDEB  command  line  in  the  form 
command^'  (for  example,  /"r;d;q").  These  commands,  which  must  precede  the  filename 
of  the  program  being  debugged,  are  carried  out  immediately  when  SYMDEB  is  loaded. 
(This  is  a  convenient  way  to  invoke  SYMDEB  and  execute  a  series  of  batch  commands.) 

The  parameters  for  a  SYMDEB  command  include  symbols;  line  numbers;  addresses; 
ranges;  and  8-bit,  l6-bit,  32-bit,  or  floating-point  values,  expressions,  and  lists.  Multiple 
parameters  can  be  separated  by  spaces,  tabs,  or  commas. 

A  symbol  is  a  name  that  represents  a  register,  an  absolute  value,  a  segment  address,  or  a 
segment  offset.  A  symbol  consists  of  one  or  more  characters  but  always  begins  with  a  let¬ 
ter,  an  underscore  (_),  a  question  mark  (?),  an  at  sign  (@),  or  a  dollar  sign  ($).  The  names 
of  the  various  8086/8088/80286  registers  and  CPU  flags  are  built  into  SYMDEB  and  can  be 
used  at  any  time.  Other  symbols  can  be  used  only  when  one  or  more  symbol  files  have 
been  loaded  in  conjunction  with  the  program  to  be  debugged. 

Note:  SYMDEB  regards  symbols  whose  spellings  differ  only  in  case  as  the  same  symbol. 

A  unique  symbol  name  that  does  not  conflict  with  programming  instructions,  register 
names,  or  hexadecimal  numbers  should  always  be  used. 

In  MASM  programs,  symbols  must  be  declared  PUBLIC  in  the  source  code  in  order  to  be 
accessible  during  debugging  (except  for  segment  and  group  names,  which  are  PUBLIC  by 
default).  In  programs  compiled  with  the  current  versions  of  Microsoft  C,  FORTRAN, 
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and  Pascal,  all  symbols  are  passed  through  for  debugging  if  the  proper  compilation  switch 
is  used;  however,  familiarity  with  the  compiler’s  particular  naming  conventions  is  neces¬ 
sary  (for  example,  the  Microsoft  C  Compiler  adds  an  underscore  character  to  the  beginning 
of  every  symbol). 

A  line  number  is  a  combination  of  decimal  numbers,  filenames,  and  symbols  that  specifies 
a  unique  line  of  text  in  a  program  source  file.  Line  numbers  always  start  with  a  dot  charac¬ 
ter  (.)  and  take  one  of  the  following  forms: 

.  [filename']  linenumber 
.-^displacement 
.-displacement 
.symbol[-^  displacement] 

.symbol[-displacement] 

The  second  and  third  variations  specify  a  line  relative  to  the  current  line  number;  the 
fourth  and  fifth  specify  a  line  number  relative  to  a  designated  symbol.  Line  numbers  can 
be  used  only  with  programs  developed  with  compilers  that  generate  line-number  informa¬ 
tion.  Programs  developed  with  MASM  or  an  incompatible  compiler  cannot  generate  line 
numbers. 

An  address  identifies  a  unique  location  in  memory.  An  address  can  be  a  simple  offset  or  a 
complete  address  consisting  of  two  l6-bit  values  in  the  form  segmentioffset.  Each  compo¬ 
nent  can  be  a  valid  symbol  (including  CS,  DS,  ES,  or  SS,  in  the  case  of  segments),  a  l6-bit 
hexadecimal  number  in  the  range  0  through  FFFFH,  or  a  symbol  plus  or  minus  a  displace¬ 
ment.  When  the  segment  portion  of  an  address  is  absent,  the  segment  specified  in  the 
previous  instance  of  the  same  command  is  used;  if  no  segment  was  previously  specified, 
SYMDEB  uses  DS  unless  an  A,  G,  L,  P,  T,  U,  or  W  command  is  used,  in  which  case  SYMDEB 
uses  CS. 

A  range  specifies  an  area  of  memory  or  a  number  of  data  items  and  can  be  expressed  as 
either  two  addresses  or  a  starting  address  and  a  length.  A  length  is  represented  by  the  letter 
L  followed  by  a  hexadecimal  value  in  the  range  0  through  FFFFH.  The  meaning  of  the 
length  varies  with  the  SYMDEB  command  used:  The  length  can  signify  a  number  of  bytes, 
words,  doublewords,  real  numbers,  machine  instructions,  or  source-code  lines.  If  a  com¬ 
mand  requires  a  range  and  the  ending  address  is  not  supplied,  SYMDEB  usually  assumes 
128  bytes. 

A  value  represents  an  integral  number  and  is  a  combination  of  one  or  more  digits.  The 
default  base  for  values  is  hexadecimal,  except  in  the  case  of  floating-point  numbers,  but 
other  bases  can  be  used  by  appending  a  radix  character  (Y  for  binary,  O  or  Q  for  octal,  T 
for  decimal,  H  for  hexadecimal)  in  either  uppercase  or  lowercase.  For  example,  the  follow¬ 
ing  values  are  equivalent: 

0040  OlOOQ 

0040H  OlOOO 

0064t  lOOOOOOY 
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Doubleword  (32-bit)  values  are  entered  as  two  hexadecimal  integers  separated  by  a  colon 
character  (:).  Real  numbers  are  always  entered  in  decimal  radix,  with  or  without  a  decimal 
point  or  exponent.  Leading  zeros  can  be  omitted. 

An  expression  is  a  combination  of  symbols,  numeric  constants,  and  operators  that  evalu¬ 
ates  to  an  8-,  I6-,  or  32-bit  value.  An  expression  can  be  used  in  place  of  a  simple  value  in 
any  command.  Unary  address  operators  use  DS  as  the  default  segment  for  addresses.  Ex¬ 
pressions  are  evaluated  in  order  of  operator  precedence;  operators  with  equal  precedence 
are  evaluated  from  left  to  right.  Parentheses  can  be  used  to  override  the  normal  operator 
precedence. 

The  available  unary  operators,  listed  in  order  of  precedence  from  highest  to  lowest,  are 


Operator  Meaning 


+ 


NOT 

SEG 

OFF 

BY 

WO 

DW 

POI 

PORT 

WPORT 


Unary  plus 
Unary  minus 

One’s  (bitwise)  complement 
Segment  address  of  operand 
Offset  of  operand 

Low-order  byte  from  specified  address 
Low-order  word  from  specified  address 
Doubleword  from  specified  address 
Pointer  from  specified  address  (same  as  DW) 
Byte  input  from  specified  port 
Word  input  from  specified  port 


The  available  binary  operators,  listed  in  order  of  precedence  from  highest  to  lowest,  are 


Operator  Meaning 

*  Multiplication 

/  Integer  division 

MOD  Modulus 

:  Segment  override 

+  Addition 

-  Subtraction 

AND  Bitwise  Boolean  AND 

XOR  Bitwise  Boolean  Exclusive  OR 

OR  Bitwise  Boolean  Inclusive  OR 

A  list  is  composed  of  one  or  more  values,  expressions,  or  strings,  separated  by  spaces  or 
commas.  A  string  is  one  or  more  ASCII  characters,  enclosed  within  single  or  double  quota¬ 
tion  marks.  Case  is  significant  within  a  string.  If  the  same  type  of  quote  character  that  is 
used  to  delimit  the  string  occurs  inside  the  string,  the  character  must  be  doubled  inside  the 
string  in  order  to  be  interpreted  correctly  (for  example, "A  ""quoted""  word"). 
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In  a  few  cases,  SYMDEB  displays  a  specific  and  informative  error  message  in  response  to 
an  invalid  command.  In  general,  though,  SYMDEB  responds  in  a  generic  fashion,  pointing 
to  the  approximate  location  of  the  error  with  a  caret  character  (^),  followed  by  the  word 
Error.  For  example: 

-D  CS:100,CS:80  <Enter> 

Error 

SYMDEB  maintains  a  set  of  virtual  CPU  registers  and  flags  for  a  program  being  debugged. 
These  registers  can  be  examined  and  modified  with  SYMDEB  commands.  When  a  pro¬ 
gram  is  first  loaded  for  debugging,  the  virtual  registers  are  initialized  with  the  following 
values: 


Register 

•COM  Program 

.EXE  Program 

AX 

Valid  drive  code 

Valid  drive  code 

BX 

Upper  half  of  program  size 

Upper  half  of  program  size 

cx 

Lower  half  of  program  size 

Lower  half  of  program  size 

DX 

Zero 

Zero 

SI 

Zero 

Zero 

DI 

Zero 

Zero 

BP 

Zero 

Zero 

SP 

FFFEH  or  top  of  available 

Size  of  stack  segment 

memory  minus  2 

IP 

lOOH 

Offset  of  entry  point  within  target 

program’s  code  segment 

cs 

PSP 

Base  of  target  program’s  code  segment 

DS 

PSP 

PSP 

ES 

PSP 

PSP 

ss 

PSP 

Base  of  target  program’s  stack  segment 

Note:  SYMDEB  checks  the  first  three  parameters  in  the  command  line.  If  the  second  and 
third  parameters  are  filenames,  SYMDEB  checks  any  drive  specifications  with  those  file¬ 
names  to  verify  that  they  designate  valid  drives.  Register  AX  contains  one  of  the  following 

codes: 

Code 

Meaning 

OOOOH  The  drives  specified  with  the  second  and  third  filenames  are  both  valid,  or 
only  one  filename  was  specified  in  the  command  line. 

OOFFH  The  drive  specified  with  the  second  filename  is  invalid. 

FFOOH  The  drive  specified  with  the  third  filename  is  invalid. 

FFFFH  The  drives  specified  with  the  second  and  third  filenames  are  both  invalid. 
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Before  SYMDEB  transfers  control  to  the  target  program,  it  saves  the  actual  CPU  registers 
and  then  loads  them  with  the  current  values  of  the  virtual  registers;  conversely,  when  con¬ 
trol  reverts  to  SYMDEB  from  the  target  program,  the  returned  register  contents  are  stored 
back  into  the  virtual  register  set  for  inspection  and  alteration  by  the  SYMDEB  user. 

Examples 

To  prepare  the  program  CLEAN.ASM  for  debugging  with  SYMDEB,  declare  all  vital  labels, 
procedures,  and  variable  names  in  the  source  program  PUBLIC.  To  assemble  the  program, 
type 

OMASM  CLEAN;  <Enter> 

This  produces  the  relocatable  object  module  CLEAN.OBJ.  Then,  to  link  the  object  module, 
type 

OLINK  /MAP  CLEAN;  <Enter> 

This  results  in  the  executable  program  file  CLEAN.EXE  and  the  map  file  CLEAN.MAP. 

Note:  The  /MAP  switch  must  be  used  even  if  a  map  file  is  specified  in  the  command  line. 
Finally,  to  create  the  symbol  information  file  required  by  SYMDEB,  type 

OMAPSYM  CLEAN  <Enter> 

At  this  point,  begin  symbolic  debugging  by  typing 

OSYMDEB  CLEAN. SYM  CLEAN.EXE  <Enter> 

Any  run-time  command-line  parameters  required  by  the  CLEAN  program  may  be  placed 
in  the  SYMDEB  command  line  after  the  filename  CLEAN.EXE. 

To  prepare  the  program  SHELL.C  for  debugging  with  SYMDEB,  first  compile  the  program 
with  the  switches  that  disable  optimization  and  cause  line-number  information  to  be  writ¬ 
ten  to  the  relocatable  object  module: 

OMSC  /Zd  /Od  SHELL;  <Enter> 

Next,  to  convert  the  object  module  to  an  executable  program  and  create  a  map  file  with 
line-number  information,  type 

OLINK  /MAP  /LI  SHELL;  <Enter> 

To  create  the  symbol  information  file  required  by  SYMDEB  for  symbolic  debugging,  type 

OMAPSYM  SHELL  <Enter> 

To  begin  debugging,  type 

OSYMDEB  SHELL. SYM  SHELL.EXE  <Enter> 
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To  use  the  SYMDEB  utility  to  inspect  or  modify  memory  or  to  read,  modify,  and  write 
absolute  disk  sectors,  type 

OSYMDEB  <Enter> 

Message 

File  not  found 

The  filename  supplied  as  the  first  parameter  in  the  SYMDEB  command  line  cannot  be 
found. 
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SYMDEB:  A 

Assemble  Machine  Instructions 


Purpose 

Allows  entry  of  assembler  mnemonics  and  translates  them  into  executable  machine  code. 

Syntax 

A  [address] 
where: 

address  is  the  starting  location  for  the  assembled  machine  code. 

Description 

The  Assemble  Machine  Instructions  (A)  command  accepts  assembly-language  statements, 
rather  than  hexadecimal  values,  for  the  Intel  8086/8088, 80186,  and  80286  (running  in  real 
mode)  microprocessors  and  the  Intel  8087  and  80287  math  coprocessors  and  assembles 
each  statement  into  executable  machine  language. 

The  address  parameter  specifies  the  location  where  entry  of  assembly-language  mne¬ 
monics  will  begin.  If  address  is  omitted,  SYMDEB  uses  the  last  address  generated  by  the 
previous  A  command;  if  there  was  no  previous  A  command,  SYMDEB  uses  the  current 
value  of  the  target  program’s  CS:IP  registers. 

After  the  user  enters  an  A  command,  SYMDEB  prompts  for  each  assembly-language  state¬ 
ment  by  displaying  the  address  (a  segment  and  an  offset)  in  which  the  assembled  code  will 
be  stored.  When  the  user  presses  the  Enter  key,  SYMDEB  translates  the  assembly-language 
statement  and  stores  each  byte  of  the  resulting  machine  instruction  sequentially  in  mem¬ 
ory  (overwriting  any  existing  information),  beginning  at  the  displayed  address.  SYMDEB 
then  displays  the  address  following  the  last  byte  of  the  machine  instruction  to  prompt  the 
user  to  enter  the  next  assembled  instruction.  The  user  can  terminate  assembly  mode  by 
pressing  the  Enter  key  in  response  to  the  address  prompt. 

The  assembly-language  statements  accepted  by  the  SYMDEB  A  command  have  some 
slight  syntactic  differences  and  restrictions  compared  with  the  Microsoft  Macro  Assembler 
programming  statements.  These  differences  can  be  summarized  as  follows: 

•  All  numbers  are  assumed  to  be  hexadecimal  integers  unless  otherwise  specified  with 
a  radix  character  suffix. 

•  Segment  overrides  must  be  specified  by  preceding  the  entire  instruction  with  CS:, 

DS:,  ES:,  or  SS:. 

•  File  control  directives  (NAME,  PAGE,  TITLE,  and  so  forth),  macro  definitions,  record 
structures,  and  conditional  assembly  directives  are  not  supported  by  SYMDEB. 
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•  When  the  data  type  (word  or  byte)  is  not  implicit  in  the  instruction,  the  type  must  be 
specified  by  preceding  the  operand  with  BYTE  PTR  (or  BY),  WORD  PTR  (or  WO), 
DWORD  PTR  (or  DW),  QWORD  PTR  (or  QW),  or  TBYTE  PTR  (or  TB). 

•  In  a  string  operation,  the  size  of  the  string  must  be  specified  with  a  B  (byte)  or  W 
(word)  added  to  the  string  instruction  mnemonic  (for  example,  LODSB  or  LODSW). 

•  The  DB  and  DW  instructions  accept  a  parameter  of  the  type  list  and  assemble  byte 
and  word  values  directly  into  memory. 

•  The  W\IT  or  FWAIT  opcodes  for  8087/80287  assembler  statements  are  not  generated 
by  the  system  and  must  be  coded  explicitly.  (Note:  8087/80287  instructions  can  be  as¬ 
sembled  if  the  system  is  not  equipped  with  a  math  coprocessor,  but  the  system  will 
crash  if  an  attempt  is  made  to  execute  them.) 

•  Addresses  must  be  enclosed  in  square  brackets  to  be  differentiated  from  immediate 
operands. 

•  Repeat  prefixes  such  as  REP,  REPZ,  and  REPNZ  can  be  entered  either  alone  on  a  line 
preceding  the  statement  they  affect  or  on  the  same  line  immediately  preceding  the 
statement. 

•  The  assembler  will  generate  the  optimal  form  (SHORT,  NEAR,  or  FAR)  for  jumps  or 
calls,  depending  on  the  destination  address,  but  these  can  be  overridden  if  the 
operand  is  preceded  with  a  NEAR  (or  NE)  or  FAR  prefix. 

•  The  mnemonic  for  a  FAR  RETURN  is  RETF. 

Examples 

To  begin  assembling  code  at  address  CSiOlOOH,  type 

-A  100  <Enter> 

To  assemble  the  instruction  sequence 

LODS  WORD  PTR  [SI] 

XCHG  BX,AX 
JMP  [BX] 

beginning  at  address  CS:0100H,  the  following  dialogue  would  take  place: 

-A  100  <Enter> 

1983:0100  LODSW  <Enter> 

1983:0101  XCHG  BX,AX  <Enter> 

1983:0103  JMP  [BX]  <Enter> 

1983:0105  <Enter> 

To  continue  assembling  at  the  last  address  generated  by  a  previous  A  command 
(1983:0105H  in  the  preceding  example),  type 

-A  <Enter> 
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Clear  Breakpoints 


Purpose 

Permanently  removes  sticky  breakpoints. 

Syntax 

BC» 

or 

BC  list 
where: 

•  represents  all  sticky  breakpoints. 

list  is  one  or  more  integers  (sticky  breakpoint  numbers)  in  the  range  0  through  9. 

Description 

The  Clear  Breakpoints  (BC)  command  permanently  clears  the  sticky  breakpoints  pre¬ 
viously  set  with  the  Set  Breakpoints  (BP)  command.  A  sticky  breakpoint  remains  in  mem¬ 
ory  throughout  a  SYMDEB  session,  unlike  a  breakpoint  set  with  the  Go  (G)  command, 
which  remains  in  effect  only  while  the  G  command  executes. 

If  an  asterisk  character  (*)  follows  the  BC  command,  SYMDEB  deletes  all  sticky  break¬ 
points.  If  a  list  parameter  containing  one  or  more  sticky  breakpoint  numbers  in  the  range 
0  through  9  follows  the  BC  command,  SYMDEB  selectively  deletes  sticky  breakpoints. 
Each  sticky  breakpoint  is  assigned  a  number  when  the  breakpoint  is  created  with  the  BP 
command.  The  List  Breakpoints  (BL)  command  can  be  used  to  display  all  current  sticky 
breakpoint  locations  and  numbers.  Breakpoint  numbers  should  be  separated  by  spaces. 

Sticky  breakpoints  can  be  temporarily  disabled  with  the  Disable  Breakpoints  (BD)  com¬ 
mand  and  subsequently  re-enabled  with  the  Enable  Breakpoints  (BE)  command. 

Examples 

To  clear  sticky  breakpoints  0, 4,  and  8,  type 

-BC  0  4  8  <Enter> 

To  clear  all  sticky  breakpoints,  type 

-BC  ♦  <Enter> 
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Messages 

Bad  breakpoint  number!  (0-9) 

A  sticky  breakpoint  number  in  the  command  line  was  not  an  integer  in  the  range  0 
through  9. 

Breakpoint  list  or  **'  expected! 

The  BC  command  was  entered  without  parameters. 
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Disable  Breakpoints 


Purpose 

Temporarily  disables  sticky  breakpoints. 

Syntax 

BD* 

or 

BD  list 
where: 

*  represents  all  sticky  breakpoints. 

list  is  one  or  more  integers  (sticky  breakpoint  numbers)  in  the  range  0  through  9. 

Description 

The  Disable  Breakpoints  (BD)  command  temporarily  disables  the  sticky  breakpoints 
previously  set  with  the  Set  Breakpoints  (BP)  command.  A  sticky  breakpoint  remains  in 
memory  throughout  a  SYMDEB  session,  unlike  a  breakpoint  set  with  the  Go  (G)  com¬ 
mand,  which  remains  in  effect  only  while  the  G  command  executes. 

If  an  asterisk  character  (♦)  follows  the  BD  command,  SYMDEB  disables  all  sticky  break¬ 
points.  If  a  list  parameter  containing  one  or  more  sticky  breakpoint  numbers  in  the  range 
0  through  9  follows  the  BD  command,  SYMDEB  selectively  disables  sticky  breakpoints. 
Each  sticky  breakpoint  is  assigned  a  number  when  the  breakpoint  is  created  with  the  BP 
command.  The  List  Breakpoints  (BL)  command  can  be  used  to  display  all  current  sticky 
breakpoint  locations  and  numbers.  Breakpoint  numbers  should  be  separated  by  spaces. 

Sticky  breakpoints  disabled  with  the  BD  command  can  be  re-enabled  with  the  Enable 
Breakpoints  (BE)  command.  The  Clear  Breakpoints  (BC)  command  can  be  used  to  per¬ 
manently  delete  a  sticky  breakpoint. 

Examples 

To  disable  sticky  breakpoints  0, 4,  and  8,  type 

“BD  048  <Enter> 

To  disable  all  sticky  breakpoints,  type 

“BD  *  <Enter> 
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Messages 

Bad  breakpoint  number!  (0-9) 

A  sticky  breakpoint  number  in  the  command  line  was  not  an  integer  in  the  range  0 
through  9. 

Breakpoint  list  or  expected! 

The  BD  command  was  entered  without  parameters. 
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Enable  Breakpoints 


Purpose 

Enables  disabled  sticky  breakpoints. 

Syntax 

BE* 

or 

BE  list 
where: 

♦  represents  all  sticky  breakpoints. 

list  is  one  or  more  integers  (sticky  breakpoint  numbers)  in  the  range  0  through  9. 

Description 

The  Enable  Breakpoints  (BE)  command  enables  the  sticky  breakpoints  disabled  with  the 
Disable  Breakpoints  (BD)  command.  A  sticky  breakpoint  remains  in  memory  throughout 
a  SYMDEB  session,  unlike  a  breakpoint  set  with  the  Go  (G)  command,  which  remains  in 
effect  only  while  the  G  command  executes. 

If  an  asterisk  (♦)  character  follows  the  BE  command,  SYMDEB  enables  all  sticky  break¬ 
points.  If  a  list  parameter  containing  one  or  more  sticky  breakpoint  numbers  in  the  range 
0  through  9  follows  the  BE  command,  SYMDEB  selectively  enables  sticky  breakpoints. 
Each  sticky  breakpoint  is  assigned  a  number  when  the  breakpoint  is  created  with  the  Set 
Breakpoints  (BP)  command.  The  List  Breakpoints  (BL)  command  can  be  used  to  display 
all  current  sticky  breakpoint  locations  and  numbers.  Breakpoint  numbers  should  be  sepa¬ 
rated  by  spaces. 

Examples 

To  enable  sticky  breakpoints  0, 4,  and  8,  type 

-BE  048  <Enter> 

To  enable  all  sticky  breakpoints,  type 

-BE  *  <Enter> 
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Messages 

Bad  breakpoint  number!  (0  -  9) 

A  sticky  breakpoint  number  in  the  command  line  was  not  an  integer  in  the  range  0 
through  9. 

Breakpoint  list  or expected! 

The  BE  command  was  entered  without  parameters. 
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List  Breakpoints 


Purpose 

Displays  information  about  all  sticky  breakpoints. 

Syntax 

BL 

Description 

The  List  Breakpoints  (BL)  command  lists  the  current  status  of  each  sticky  breakpoint 
created  with  the  Set  Breakpoints  (BP)  command.  A  sticky  breakpoint  remains  in  memory 
throughout  a  SYMDEB  session,  unlike  a  breakpoint  set  with  the  Go  (G)  command,  which 
remains  in  effect  only  while  the  G  command  executes. 

The  BL  command  lists  each  sticky  breakpoint  number,  its  status  code,  its  address  in  the 
target  program,  the  number  of  passes  remaining,  and  the  initial  number  of  passes  speci¬ 
fied  with  the  BP  command  (in  parentheses).  If  source  display  mode  was  selected  with  the 
Enable  Source  Display  Mode  (S+)  command,  SYMDEB  also  displays  the  source-file  name 
and  the  line  number  that  corresponds  to  each  breakpoint  location.  Breakpoint  status 
codes  are 

e  Enabled 
d  Disabled 
V  Virtual 

(A  virtual  breakpoint  is  a  sticky  breakpoint  set  at  a  symbol  contained  in  a  .EXE  file  that  has 
not  yet  been  loaded  into  SYMDEB.) 

Example 

To  view  the  current  status  of  all  breakpoints,  type 

-BL  <Enter> 

If  the  BP  commands 

-BPO  _TEXT:_main  <Enter> 

-BPl  _TEXT:_printf  <Enter> 

were  previously  entered,  the  BL  command  displays 

0  e  456E:0010  [_TEXT:_main]  dump. C: 32 
1  e  456E:0612  [_TEXT :_printf ] 
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Set  Breakpoints 


Purpose 

Sets  sticky  breakpoint  locations  within  the  program  being  debugged. 

Syntax 

BP[w]  address[passcount]  [^'commands''] 
where: 
n 

address 
passcount 

^'commands'' 

Description 

The  Set  Breakpoints  (BP)  command  sets  a  sticky  breakpoint  in  the  program  being 
debugged.  A  sticky  breakpoint  remains  in  memory  throughout  a  SYMDEB  session,  unlike 
a  breakpoint  set  with  the  Go  (G)  command,  which  remains  in  effect  only  while  the  G 
command  executes.  When  the  target  program  reaches  the  breakpoint,  execution  of  the 
program  is  suspended  and  control  returns  to  SYMDEB.  SYMDEB  displays  the  contents  of 
the  registers  and  flags,  followed  by  a  prompt  so  that  the  user  can  enter  more  commands. 

The  optional  n  parameter  associates  an  integer  in  the  range  0  through  9,  called  the  break¬ 
point  number,  with  the  sticky  breakpoint  location.  If  n  is  omitted,  the  next  available 
breakpoint  number  is  used.  No  space  is  allowed  between  BP  and  n. 

The  address  parameter  must  point  to  the  first  byte  of  a  machine  instruction  in  the  pro¬ 
gram.  This  parameter  may  be  a  symbol,  a  literal  address,  or  a  source-code  line  number.  If 
a  segment  is  not  included,  SYMDEB  uses  the  target  program’s  CS  register. 

The  optional  passcount  parameter  is  the  number  of  times  execution  should  pass  through 
the  specified  location  before  the  break  is  taken  and  control  is  returned  to  SYMDEB.  The 
value  of  passcount  must  be  a  hexadecimal  number  in  the  range  0  through  FFFFH 
(default  =  0). 

The  optional commands"  parameter  is  one  or  more  SYMDEB  commands  with  their 
associated  parameters.  Each  command  must  be  separated  from  the  others  by  a  semicolon 
character  (;)  and  the  entire  list  enclosed  in  double  quotation  marks  (").  A  maximum  of  30 
characters  can  be  specified  within  the  quotation  marks.  The  commands  are  executed 
whenever  the  break  is  taken. 


is  the  sticky  breakpoint  number  (0-9). 

is  the  location  of  the  breakpoint  in  the  target  program. 

is  the  number  of  times  the  instruction  at  address  should  be  executed 

before  the  breakpoint  is  taken. 

is  one  or  more  SYMDEB  commands,  separated  by  semicolons.  The  entire 
list  must  be  enclosed  in  double  quotation  marks.  (Limit  =  30  characters.) 


1 07 2  The  MS-DOS  Encyclopedia 


SYMDEB:  BP 


Examples 

To  set  a  sticky  breakpoint  at  location  next^ file  in  the  target  program  and  dump  the  con¬ 
tents  of  memory  locations  DSiOOOOH  through  DSrOOFFH  when  the  breakpoint  is  reached, 
type 

-BP  NEXT_FILE  "DB  DS:0  LI  00”  <Enter> 

To  associate  the  breakpoint  number  4  with  the  location  CS:4230H  in  the  program  being 
debugged  and  pass  the  breakpoint  16  (lOH)  times  before  suspending  execution  of  the  pro¬ 
gram,  type 

-BP4  CS:4230  10  <Enter> 

Messages 

Bad  breakpoint  number!  (0-9) 

A  sticky  breakpoint  number  in  the  command  line  was  not  an  integer  in  the  range  0 
through  9. 

Breakpoint  command  too  long! 

The  ''commands'^  parameter  exceeded  30  characters. 

Breakpoint  error! 

The  BP  command  was  entered  without  an  address  parameter. 

Breakpoint  redefined! 

A  new  address  was  assigned  to  an  exist^g  breakpoint  number,  or  an  attempt  was  made  to 
create  a  breakpoint  with  the  same  address  as  an  existing  breakpoint. 

Duplicate  breakpoint  ignored! 

An  attempt  was  made  to  change  an  existing  breakpoint  to  a  breakpoint  already  specified 
in  the  breakpoint  list. 

Too  many  breakpoints! 

No  more  sticky  breakpoints  are  available. 
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SYMDEB:  C 

Compare  Memory  Areas 

Purpose 

Compares  two  areas  of  memory  and  reports  any  differences. 

Syntax 

C  range  address 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  first  area  of  memory  to  be  compared. 
address  points  to  the  beginning  of  the  second  area  of  memory  to  be  compared. 

Description 

The  Compare  Memory  Areas  (C)  command  compares  the  contents  of  two  areas  of  mem¬ 
ory.  The  location  and  contents  of  any  differing  bytes  are  listed  in  the  following  form: 

addressl  bytel  byte2  address2 

If  no  differences  are  found,  the  SYMDEB  prompt  returns. 

The  range  parameter  specifies  the  first  through  last  addresses  or  the  starting  address  and 
length  in  bytes  of  the  first  area  of  memory  to  be  compared. 

The  address  parameter  points  to  the  beginning  of  the  second  area  of  memory  to  be  com¬ 
pared,  which  is  the  same  size  as  range.  If  a  segment  is  not  included  in  either  range  or 
address,  SYMDEB  uses  DS. 

Example 

To  compare  the  64  bytes  beginning  at  CS:CE00H  with  the  64  bytes  beginning  at 
CS:CF0AH,  type 

-C  CS:CE00,CE3F  CSiCFOA  <Enter> 

or 

-C  CSiCEOO  L40  CS:CF0A  <Enter> 

If  any  differences  are  found,  SYMDEB  displays  them  in  the  following  format: 

2124:CE06  00  FF  2124:CF10 
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SYMDEB:  D 

Display  Memory 


Purpose 

Displays  the  contents  of  an  area  of  memory. 

Syntax 

D  [range] 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  of  memory  to  be  displayed. 

Description 

The  Display  Memory  (D)  command  displays  the  contents  of  a  specified  range  of  memory 
addresses  in  the  same  format  used  in  the  most  recent  Display  command  (DA,  DB,  DD,  DL, 
DS,  DT,  or  DW).  If  no  Display  command  has  previously  been  entered,  the  memory  is  dis¬ 
played  in  hexadecimal  bytes  and  their  ASCII  equivalents  (the  DB  format). 

The  range  parameter  specifies  the  starting  and  ending  addresses  of  the  memory  area  to 
be  displayed  or  the  starting  address  followed  by  the  length  of  the  area,  expressed  by  an  L 
and  the  hexadecimal  number  of  data  items  to  be  displayed.  When  range  does  not  include 
a  segment,  SYMDEB  uses  DS. 

The  size  in  bytes  of  each  item  and  the  default  value  for  the  length  depend  on  the  type  of 
Display  command  used:  the  Display  Byte  (DB),  Display  Doubleword  (DD),  and  Display 
Word  (DW)  commands  default  to  a  length  of  128  (80H)  bytes;  Display  ASCII  (DA)  displays 
128  bytes  or  up  to  a  null  byte,  whichever  is  smaller;  Display  Short  Reals  (DS),  Display  Long 
Reals  (DL),  and  Display  10-Byte  Reals  (DT)  default  to  the  display  of  one  floating-point 
number. 

If  a  Display  command  has  not  previously  been  used  and  range  is  omitted  from  a  D  com¬ 
mand,  the  display  starts  at  the  address  specified  in  the  target  program's  CS:IP  registers.  If  a 
Display  command  has  previously  been  used  and  range  is  omitted  from  a  D  command,  the 
display  starts  at  the  memory  address  following  the  last  address  displayed  by  the  most  re¬ 
cent  Display  command. 

Examples 

Assume  that  the  only  Display  commands  used  during  this  SYMDEB  session  are  D  and  DB. 
To  display  the  contents  of  the  128  bytes  of  memory  beginning  at  offset  lOOH  in  the  pro¬ 
gram’s  DGROUP,  type 

-D  DGROUP: 01 00  <Enter> 
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SYMDEB  displays  the  contents  of  the  range  of  memory  addresses  in  the  following  format: 


7F00:0100 

20 

64 

65 

76 

69 

63 

65 

OD-OA 

00 

60 

39 

OD 

OA 

00 

7C 

device . . . ' 9 . .  .  ! 

7F00:0110 

39 

08 

20 

08 

00 

81 

39 

04-1B 

5B 

32 

4A 

42 

BD 

1 1 

44 

9.  . . .9. . [2JB=.D 

7F00:0120 

2E 

26 

45 

AF 

11 

47 

B3 

11-48 

A5 

11 

4C 

B8 

11 

4E 

D3 

.&E/.G3.H%.L8.NS 

7F00:0130 

1 1 

50 

DF 

11 

51 

AB 

11 

54-DF 

IE 

56 

37 

1  1 

5F 

9F 

16 

.P_.Q+.T_.V7 _ 

7F00:0140 

24 

CO 

11 

00 

03 

4E 

4F 

54-C1 

07 

OA 

45 

52 

52 

4F 

52 

$@. . .NOTA. .ERROR 

7F00:0150 

4C 

45 

56 

45 

4C 

85 

08 

05-45 

58 

49 

53 

54 

18 

08 

00 

LEVEL. . .EXIST. .  . 

7F00:0160 

03 

44 

49 

52 

03 

91 

OC 

06-52 

45 

4E 

41 

4D 

45 

01 

CO 

.DIR _ RENAME.  @ 

7F00:0170 

OF 

03 

52 

45 

4E 

01 

CO 

OF-05 

45 

52 

41 

53 

45 

01 

68 

. . REN . 0 . . ERASE . h 

To  view  the  next  128  bytes  of  memory,  type 


-D  <Enter> 

SYMDEB  displays  the  contents  of  memory  addresses  7F00:0180H  through  7F00:01FFH. 
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SYMDEB:  DA 

Display  ASCII 


Purpose 

Displays  the  contents  of  memory  in  ASCII  format. 

Syntax 

DA  [range] 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  of  memory  to  be  displayed. 

Description 

The  Display  ASCII  (DA)  command  displays  the  contents  of  a  specified  range  of  memory 
addresses  in  ASCII  format. 

The  range  parameter  specifies  the  starting  and  ending  addresses  of  the  memory  area  to 
be  displayed  in  ASCII  format  or  the  starting  address  followed  by  the  length  of  the  area,  ex¬ 
pressed  by  an  L  and  a  hexadecimal  number  of  bytes.  When  range  does  not  include  a 
segment,  SYMDEB  uses  DS. 

If  a  Display  command  has  not  previously  been  used  and  range  is  omitted  from  a  DA  com¬ 
mand,  the  display  starts  at  the  address  specified  in  the  target  program’s  CS:IP  registers.  If  a 
Display  command  has  previously  been  used  and  range  is  omitted  from  a  DA  command, 
the  display  starts  at  the  memory  address  following  the  last  address  displayed  by  the  most 
recent  Display  command. 

When  a  range  is  not  explicit  in  a  DA  command,  the  display  terminates  after  128  bytes  or 
when  a  null  (zero)  byte  is  encountered.  If  a  range  is  specified,  the  entire  range  is  dis¬ 
played,  including  any  null  bytes,  with  nonprinting  characters  displayed  as  period  (.) 
characters. 

Each  line  of  the  display  is  formatted  as  a  segment  and  offset,  followed  by  the  contents  of 
l6  bytes  of  memory  (or  less  if  a  null  byte  was  encountered)  represented  as  an  ASCII  string. 

See  also  PROGRAMMING  UTILITIES:  symdeb:ea. 

Examples 

If  memory  beginning  at  location  7F00:0100H  contains  the  characters  This  is  a  test  string 
followed  by  a  null  (zero)  byte,  the  command 

-DA  7F00:0100  <Enter> 
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produces  the  following  display: 

7F00:0100  This  is  a  test  string 

To  view  additional  memory  in  the  same  format,  type 

-D  <Enter> 
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SYMDEB:  DB 

Display  Bytes 


Purpose 

Displays  the  contents  of  memory  as  hexadecimal  bytes  and  their  equivalent  ASCII 
characters. 

Syntax 

DB  [range] 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  of  memory  to  be  displayed. 

Description 

The  Display  Bytes  (DB)  command  displays  the  contents  of  a  specified  range  of  memory 
addresses  as  hexadecimal  bytes  and  their  ASCII  character  equivalents.  This  is  the  default 
format  for  the  Display  Memory  (D)  command. 

The  range  parameter  specifies  the  starting  and  ending  addresses  of  the  memory  area  to 
be  displayed  or  the  starting  address  followed  by  the  length  of  the  area,  expressed  by  an  L 
and  a  hexadecimal  number  of  bytes.  When  range  does  not  include  a  segment,  SYMDEB 
uses  DS. 

If  a  Display  command  has  not  previously  been  used  and  range  is  omitted  from  a  DB  com¬ 
mand,  the  display  starts  at  the  address  specified  in  the  target  program’s  CS:IP  registers.  If  a 
Display  command  has  previously  been  used  and  range  is  omitted  from  a  DB  command, 
the  display  starts  at  the  memory  address  following  the  last  address  displayed  by  the  most 
recent  Display  command.  When  a  range  is  not  explicit  in  a  DB  command,  the  display  ter¬ 
minates  after  128  bytes. 

Each  line  of  the  display  is  formatted  as  a  segment  and  offset,  followed  by  the  contents  of 
16  bytes  of  memory  represented  as  hexadecimal  values  separated  by  spaces  (except  the 
eighth  and  ninth  values,  which  are  separated  by  a  dash),  followed  by  their  ASCII  character 
equivalents  (if  any).  In  the  ASCII  section,  nonprinting  characters  are  displayed  as  periods. 

See  also  FROGRAMMING  UTILITIES:  symdeb:eb. 

Examples 

To  display  the  contents  of  the  128  bytes  of  memory  beginning  at  7F00:0100H,  type 

-DB  7F00:0100  <Enter> 
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The  contents  of  the  range  of  memory  addresses  are  displayed  in  the  following  format: 


7F00:0100 
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To  view  the  next  128  bytes  of  memory,  type 


-D  <Enter> 

SYMDEB  displays  the  contents  of  memory  addresses  7F00:0180H  through  7F00:01FFH. 
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SYMDEB:  DD 

Display  Doublewords 


Purpose 

Displays  the  contents  of  memory  in  hexadecimal  doubleword  format. 

Syntax 

DD  \rang(^ 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  of  memory  to  be  displayed. 

Description 

The  Display  Etoublewords  (DD)  command  displays  the  contents  of  a  specified  range  of 
memory  addresses  4  bytes  at  a  time,  as  if  they  were  FAR  memory  pointers  (offset  followed 
by  segment  in  reverse  byte  order). 

The  range  parameter  specifies  the  starting  and  ending  addresses  of  the  memory  to  be  dis¬ 
played  or  the  starting  address  followed  by  the  length  of  the  area,  expressed  by  an  L  and  a 
hexadecimal  number  of  doublewords.  When  range  does  not  include  a  segment,  SYMDEB 
uses  DS. 

If  a  Display  command  has  not  previously  been  used  and  range  is  omitted  from  a  DD  com¬ 
mand,  the  display  starts  at  the  address  specified  in  the  target  program’s  CS:IP  registers.  If  a 
Display  command  has  previously  been  used  and  range  is  omitted  from  a  DD  command, 
the  display  starts  at  the  memory  address  following  the  last  address  displayed  by  the  most 
recent  Display  command.  When  a  range  is  not  explicit  in  a  DD  command,  32  doublewords 
(128  bytes)  are  displayed. 

Each  line  of  the  display  is  formatted  as  a  segment  and  offset,  followed  by  the  contents  of 
16  bytes  of  memory  represented  as  4  paired  l6-bit  segments  and  offsets.  The  4  bytes  that 
make  up  the  segment  and  offset  of  each  doubleword  pointer  are  displayed  in  reverse  order 
from  their  actual  storage  in  memory. 

See  also  PROGRAMMING  UTILITIES:  symdeb:ed. 

Examples 

To  see  how  DD  represents  the  4  bytes  that  make  up  a  doubleword,  first  type 

-DB  100  <Enter> 
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This  produces  the  following  output: 

3929:0100  CF  OB  9D  OD  33  OE  C3  0E-F2  OE  06  OF  39  OF  49  OF  0  .  .  .  3.C.r. . . 9. 1. 

Then  type 


-DD  1 00  <Enter> 

This  produces  the  following  output: 

3929:0100  0D9D:0BCF  0EC3:0E33  0F06:0EF2  0F49:0F39 


Notice  that  DD  switches  the  order  of  the  first  2  bytes  in  a  4-byte  set  and  designates  them  as 
the  offset;  then  it  switches  the  order  of  the  second  2  bytes  in  the  4-byte  set  and  designates 
them  as  the  segment  address. 

To  display  the  contents  of  the  first  128  (80H)  bytes  of  the  system  interrupt  vector  table, 
which  is  based  at  address  0000:0000H,  type 

-DD  0 : 0  <Enter> 


This  produces  the  following  output: 


0000:0000 

0000:0010 

0000:0020 

0000:0030 

0000:0040 

0000:0050 

0000:0060 

0000:0070 


2075:03D2 

0070:01F0 

0AE3:0395 

0972:0B40 

0AE3:03D6 

F000:E739 

F000:E76C 

F000:FF53 


0070:01F0 

F000:FF54 

16F3:2BAD 

F000:9805 

F000:F84D 

F000:F859 

0070:0ADD 

F000:F0E4 


16F3:2C1B 

F000:9805 

F000:9805 

F000:EF57 

F000:F841 

F000:E82E 

F000:FE6E 

0000:0522 


0070:01F0 

F000:9805 

F000:9805 

0070:01F0 

0070:0D43 

F000:EFD2 

1078:3BEC 

F000:0000 


To  view  the  next  128  bytes  of  memory  in  the  same  format,  type 


-D  <Enter> 

SYMDEB  displays  the  contents  of  memory  addresses  0000:0080H  through  0000:00FFH. 
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SYMDEB:  DL 

Display  Long  Reals 


Purpose 

Displays  the  contents  of  memory  as  long  (64-bit)  floating-point  numbers. 

Syntax 

DL  [range] 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  of  memory  to  be  displayed. 

Description 

The  Display  Long  Reals  (DL)  command  displays  the  contents  of  a  specified  range  of  mem¬ 
ory  addresses  8  bytes  at  a  time,  as  hexadecimal  values  and  their  decimal  equivalents.  The 
hexadecimal  values  are  formatted  as  64-bit  floating-point  numbers.  The  decimal  values 
have  the  form 

+1-0  .decimaldigitsY/r  \--mantissa 

The  sign  of  the  number  (+  or  -)  is  followed  by  a  zero,  a  decimal  point,  and  a  maximum  of 
16  decimaldigitS',  this,  in  turn,  is  followed  by  the  designator  of  the  mantissa  (E)  and  the 
mantissa’s  sign  (+  or  -)  and  digits. 

The  range  parameter  specifies  the  starting  and  ending  addresses  of  the  memory  to  be  dis¬ 
played  or  the  starting  address  followed  by  the  length  of  the  area,  expressed  by  an  L  and  a 
hexadecimal  number  of  8-byte  values.  When  range  does  not  include  a  segment,  SYMDEB 
uses  DS. 

If  a  Display  command  has  not  previously  been  used  and  range  is  omitted  from  a  DL 
command,  the  display  starts  at  the  address  specified  in  the  target  program’s  CS:IP  regis¬ 
ters.  If  a  Display  command  has  previously  been  used  and  range  is  omitted  from  a  DL  com¬ 
mand,  the  display  starts  at  the  memory  address  following  the  last  address  displayed 
by  the  most  recent  Display  command.  When  a  range  is  not  explicit  in  a  DL  command, 
one  64-bit  floating-point  number  is  displayed. 

Each  line  of  the  display  is  formatted  as  a  segment  and  offset,  followed  by  the  contents  of 
8  bytes  of  memory  represented  as  a  hexadecimal  value,  followed  by  its  decimal  floating¬ 
point  equivalent. 

See  also  PROGRAMMING  UTILITIES:  symdeb:el. 
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Examples 

Assume  that  the  memory  beginning  at  location  DS:0100H  contains  the  value  6.624  •10-27 
(Planck’s  constant,  in  eig-seconds)  as  a  64-bit  floating-point  number.  The  command 

-DL  100  <Enter> 

produces  the  following  output: 

43E8:0100  5F  A2  20  73  75  66  80  3A  +0.6624E-26 

To  view  the  next  8  bytes  of  memory  in  the  same  format,  type 

-D  <Enter> 
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Display  Short  Reals 


Purpose 

Displays  the  contents  of  memory  as  short  (32-bit)  floating-point  numbers. 

Syntax 

DS  [range] 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  of  memory  to  be  displayed. 

Description 

The  Display  Short  Reals  (DS)  command  displays  the  contents  of  a  specified  range  of  mem¬ 
ory  addresses  4  bytes  at  a  time,  as  hexadecimal  values  and  their  decimal  equivalents.  The 
hexadecimal  values  are  formatted  as  32-bit  floating-point  numbers.  The  decimal  values 
have  the  form 

'^\-0.decimaldigitsE+  {-mantissa 

The  sign  of  the  number  (+  or  -)  is  followed  by  a  zero,  a  decimal  point,  and  a  maximum 
of  16  decimaldigits  (only  the  first  7  digits  are  significant);  this,  in  turn,  is  followed  by  the 
designator  of  the  mantissa  (E)  and  the  mantissa’s  sign  (+  or  -)  and  digits. 

The  range  parameter  specifies  the  starting  and  ending  addresses  of  the  area  of  memory  to 
be  displayed  or  the  starting  address  followed  by  the  length  of  the  area,  expressed  by  an  L 
and  a  hexadecimal  number  of  4-byte  values.  When  range  does  not  include  a  segment, 
SYMDEB  uses  DS, 

If  a  Display  command  has  not  previously  been  used  and  range  is  omitted  from  a  DS 
command,  the  display  starts  at  the  address  specified  in  the  target  program’s  CS:IP  regis¬ 
ters.  If  a  Display  command  has  previously  been  used  and  range  is  omitted  from  a  DS  com¬ 
mand,  the  display  starts  at  the  memory  address  following  the  last  address  displayed 
by  the  most  recent  Display  command.  When  a  range  is  not  explicit  in  a  DS  command,  one 
32-bit  floating-point  number  is  displayed. 

Each  line  of  the  display  is  formatted  as  a  segment  and  offset,  followed  by  the  contents  of 
4  bytes  of  memory  represented  as  a  hexadecimal  value,  followed  by  its  decimal  floating¬ 
point  equivalent. 

See  also  PROGRAMMING  UTILITIES:  symdeb:es. 
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Examples 

Assume  that  the  memory  beginning  at  location  43E8:0100H  contains  the  value  6.02  ♦10‘^23 
(Avogadro’s  number)  as  a  32-bit  floating-point  number.  The  command 

-DS  43E8:100  <Enter> 

produces  the  following  output: 

43E8:0100  F9  F4  FE  66  +0 . 60200001 7271 8952E+24 

To  view  the  next  4  bytes  of  memory  in  the  same  format,  type 

“D  <Enter> 


1086  The  MS-DOS  Encyclopedia 


SYMDEB:  DT 


SYMDEB:  DT 

Display  10-Byte  Reals 


Purpose 

Displays  the  contents  of  memory  as  10-byte  (80-bit)  floating-point  numbers. 

Syntax 

DT  [range] 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  of  memory  to  be  displayed. 

Description 

The  Display  10-Byte  Reals  (DT)  command  displays  the  contents  of  a  specified  range  of 
memory  addresses  10  bytes  at  a  time,  as  hexadecimal  values  and  their  decimal  equivalents. 
The  hexadecimal  values  are  formatted  as  80-bit  floating-point  numbers.  (This  format  is 
ordinarily  used  by  the  Intel  8087  math  coprocessor  only  for  intermediate  results  during 
chained  floating-point  calculations.)  The  decimal  value  has  the  form 

.decimaldigitsE’^ \-mantissa 

The  sign  of  the  number  (+  or  -)  is  followed  by  a  zero,  a  decimal  point,  and  a  maximum  of 
16  decimaldigits;  this,  in  turn,  is  followed  by  the  designator  of  the  mantissa  (E)  and  the 
mantissa’s  sign  (+  or  -)  and  digits. 

The  range  parameter  specifies  the  starting  and  ending  addresses  of  the  area  of  memory  to 
be  displayed  or  the  starting  address  followed  by  the  length  of  the  area,  expressed  by  an  L 
and  a  hexadecimal  number  of  10-byte  values.  When  range  does  not  include  a  segment, 
SYMDEB  uses  DS. 

If  a  Display  command  has  not  previously  been  used  and  range  is  omitted  from  a  DT 
command,  the  display  starts  at  the  address  specified  in  the  target  program’s  CS:IP  regis¬ 
ters.  If  a  Display  command  has  previously  been  used  and  range  is  omitted  from  a  DT  com¬ 
mand,  the  display  starts  at  the  memory  address  following  the  last  address  displayed 
by  the  most  recent  Display  command.  When  a  range  is  not  explicit  in  a  DT  command,  one 
10-byte  floating-point  number  is  displayed. 

Each  line  of  the  display  is  formatted  as  a  segment  and  offset,  followed  by  the  contents  of 
10  bytes  of  memory  represented  as  a  hexadecimal  value,  followed  by  its  decimal  floating¬ 
point  equivalent. 

See  also  PROGRAMMING  UTILITIES:  symdeb:et. 
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Examples 

Assume  that  the  memory  beginning  at  location  DS:0100H  contains  the  value  2.99 
(the  speed  of  light  in  centimeters  per  second)  as  an  80-bit  floating-point  number.  The 
command 

-DT  100  <Enter> 

produces  the  following  output: 

43E8:0100  00  00  00  00  60  B9  C5  DE  21  40  +0.299E+11 

To  view  the  next  10  bytes  of  memory  in  the  same  format,  type 

-D  <Enter> 
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SYlVfDEB:  DW 

Display  Words 


Purpose 

Displays  the  contents  of  memory  as  2-byte  (l6-bit)  words. 

Syntax 

DW  [range] 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  the  area  of  memory  to  be  displayed. 

Description 

The  Display  Word  (DW)  command  displays  the  contents  of  a  specified  range  of  memory 
addresses  2  bytes  at  a  time,  as  l6-bit  hexadecimal  integers. 

The  range  parameter  specifies  the  starting  and  ending  addresses  of  the  area  of  memory  to 
be  displayed  or  the  starting  address  followed  by  the  length  of  the  area,  expressed  by  an  L 
and  a  hexadecimal  number  of  words  of  memory  to  be  displayed.  When  range  does  not  in¬ 
clude  a  segment,  SYMDEB  uses  DS. 

If  a  Display  command  has  not  previously  been  used  and  range  is  omitted  from  a  DW  com¬ 
mand,  the  display  starts  at  the  address  specified  in  the  target  program’s  CS:IP  registers.  If  a 
Display  command  has  previously  been  used  and  range  is  omitted  from  a  DW  command, 
the  display  starts  at  the  memory  address  following  the  last  address  displayed  by  the  most 
recent  Display  command.  When  a  range  is  not  explicit  in  a  DW  command,  64  words 
are  displayed. 

Each  line  of  the  display  is  formatted  as  a  s^ment  and  offset,  followed  by  the  contents  of  16 
bytes  of  memory  represented  as  eight  4-digit  hexadecimal  numbers.  The  2  bytes  that  make 
up  each  word  are  displayed  in  reverse  order  from  their  actual  storage  in  memory.  That  is, 
the  first  byte  in  a  2-byte  word  is  displayed  after  the  second  byte. 

See  also  PROGRAMMING  UTILITIES:  symdeb:ew. 

Examples 

To  display  the  contents  of  the  64  words  of  memory  beginning  at  DS:0080H  in  word  format, 
type 

-DW  80  <Enter> 
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This  produces  the  following  output: 


1  FEE: 0080 

6977 

64  6E 

776F 

5C73 

696C 

0062 

494C 

3D42 

1  FEE: 0090 

3A63 

6D5C 

6373 

6C5C 

6269 

633B 

5C3A 

6977 

1FEE:00A0 

646E 

776F 

5C73 

696C 

0062 

4D54 

3D50 

3A63 

1FEE:00B0 

745C 

6D65 

0070 

4554 

504D 

633D 

5C3A 

6574 

1FEE:00C0 

706D 

4400 

4149 

3D4C 

3A63 

645C 

6169 

006C 

1FEE:00D0 

4350 

3346 

3D32 

3A63 

665C 

726F 

6874 

705C 

1FEE:00E0 

3363 

0032 

4350 

3350 

3D32 

3A63 

665C 

726F 

1FEE:00F0 

6874 

705C 

756C 

3373 

0032 

5255 

3146 

3D30 

To  view  the  next  64  words  of  memory  in  the  same  format,  type 

-D  <Enter> 

SYMDEB  displays  the  contents  of  memory  addresses  1FEE:0100H  through  1FEE:017FH. 
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SYMDEB:  E 

Enter  Data 


Purpose 

Enters  data  into  memory. 

Syntax 

E  addressUist] 
where: 

address  is  the  first  memory  location  for  storage. 

list  is  the  data  to  be  placed  into  successive  bytes  of  memory,  starting  at  address. 

Description 

The  Enter  Data  (E)  command  enters  into  memory  one  or  more  data  items,  using  the  same 
format  as  the  most  recent  Enter  command  (EA,  EB,  ED,  EL,  ES,  ET,  or  EW).  If  no  Enter 
command  has  previously  been  used,  the  data  can  be  entered  as  either  hexadecimal  values 
or  ASCII  strings  (the  EA  or  EB  format).  Any  data  previously  stored  at  the  specified  loca¬ 
tions  is  lost.  If  SYMDEB  displays  an  error  message,  no  changes  are  made. 

The  address  parameter  specifies  the  first  byte  to  be  modified.  If  address  does  not  include 
a  segment,  SYMDEB  uses  DS.  SYMDEB  increments  the  address  for  each  byte  of  data 
stored. 

The  list  parameter  must  meet  the  requirements  of  the  last  Enter  command  used.  All 
SYMDEB  Enter  commands  are  described  in  alphabetic  order  on  the  following  pages.  If  list 
is  included  in  the  command  line,  the  changes  are  made  unless  an  error  is  detected  in  the 
command  line.  If  list  is  omitted  from  the  command  line,  the  current  contents  of  address 
are  displayed,  followed  by  a  period  (.),  and  the  user  is  prompted  for  new  data.  If  no  value 
is  entered  and  the  Enter  key  is  pressed,  the  original  value  remains  unchanged  and  the  En¬ 
ter  command  is  terminated. 

Examples 

The  following  two  examples  assume  that  no  previous  Enter  commands  have  been  used  or 
that  the  most  recent  Enter  command  was  EA  or  EB. 

To  store  the  byte  values  OOH,  ODH,  and  OAH  into  the  3  bytes  beginning  at  DS:1FB3H,  type 

-E  1FB3  00  OD  OA  <Enter> 
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If  the  command 

-E  2C3  ABC  <Eri.ter> 

is  entered  and  the  last  Enter  command  used  was  E  A  or  EB,  the  value  BCH  is  stored  at 
DS:2C3H,  and  the  leading  *A’  character  on  the  hexadecimal  number  ABC  is  ignored. 
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SYMDEB:  EA 

Enter  ASCII  String 


Purpose 

Enters  an  ASCII  string  or  hexadecimal  byte  values  into  memory. 

Syntax 

EA  addressUist] 
where: 

address  is  the  first  memory  location  for  storage. 

list  is  one  or  more  ASCII  strings  or  hexadecimal  byte  values. 

Description 

The  Enter  ASCII  String  (EA)  command  enters  data  into  successive  memory  bytes.  The  data 
can  be  entered  as  either  hexadecimal  byte  values  or  ASCII  strings.  Any  data  previously 
stored  at  the  specified  locations  is  lost.  If  SYMDEB  displays  an  error  message,  no  changes 
are  made.  The  EA  command  functions  exactly  like  the  Enter  Bytes  (EB)  command. 

The  address  parameter  specifies  the  first  byte  to  be  modified.  If  address  does  not  include 
a  segment,  SYMDEB  uses  DS.  SYMDEB  increments  the  address  for  each  byte  of  data 
stored. 

The  list  parameter  is  one  or  more  ASCII  strings  and/or  hexadecimal  byte  values,  separated 
by  spaces,  commas,  or  tab  characters.  Extra  or  trailing  characters  are  ignored.  Strings  must 
be  enclosed  within  single  or  double  quotation  marks,  and  case  is  significant  within  a 
string. 

If  list  is  included  in  the  command  line,  the  changes  are  made  unless  an  error  is  detected  in 
the  command  line.  If  list  is  omitted  from  the  command  line,  the  user  is  prompted  byte  by 
byte  for  new  data,  starting  at  address.  The  current  contents  of  a  byte  are  displayed,  fol¬ 
lowed  by  a  period.  A  new  value  for  that  byte  can  be  entered  as  one  or  two  hexadecimal 
digits  (extra  characters  are  ignored),  or  the  contents  can  be  left  unchanged.  To  display  the 
next  byte,  the  user  presses  the  spacebar.  If  the  user  enters  a  minus  sign,  or  hyphen  charac¬ 
ter  (-),  instead  of  pressing  the  spacebar,  SYMDEB  backs  up  to  the  previous  byte.  A  maxi¬ 
mum  of  8  bytes  can  be  entered  on  each  input  line;  a  new  line  is  begun  each  time  an  8-byte 
boundary  is  crossed.  Data  entry  is  terminated  by  pressing  the  Enter  key  without  pressing 
the  spacebar  or  entering  any  data. 

Text  strings  can  be  used  only  as  part  of  the  list  parameter  in  an  EA  command  line;  they 
cannot  be  entered  in  response  to  an  address  prompt. 
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Example 

To  store  the  string  MAIN  MENU  into  memory  beginning  at  address  ES:0Cl4H,  type 

-EA  ES:C14  "MAIN  MENU"  <Enter> 
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SYMDEB:  EB 

Enter  Bytes 


Purpose 

Enters  hexadecimal  byte  values  or  ASCII  strings  into  memory. 

Syntax 

EB  addressUist] 
where: 

address  is  the  first  memory  location  for  storage. 

list  is  one  or  more  hexadecimal  byte  values  or  ASCII  strings. 

Description 

The  Enter  Bytes  (EB)  command  enters  data  into  successive  memory  bytes.  The  data  can 
be  entered  as  either  hexadecimal  byte  values  or  ASCII  strings.  Any  data  previously  stored 
at  the  specified  locations  is  lost.  If  SYMDEB  displays  an  error  message,  no  changes  are 
made.  The  EB  command  functions  exactly  like  the  Enter  ASCII  String  (EA)  command. 

The  address  parameter  specifies  the  first  byte  to  be  modified.  If  address  does  not  include 
a  segment,  SYMDEB  uses  DS.  SYMDEB  increments  the  address  for  each  byte  of  data 
stored. 

The  list  parameter  is  one  or  more  hexadecimal  byte  values  and/or  ASCII  strings,  separated 
by  spaces,  commas,  or  tab  characters.  Extra  or  trailing  characters  are  ignored.  Strings  must 
be  enclosed  within  single  or  double  quotation  marks,  and  case  is  significant  within  a 
string. 

If  list  is  included  in  the  command  line,  the  changes  are  made  unless  an  error  is  detected  in 
the  command  line.  If  list  is  omitted  from  the  command  line,  the  user  is  prompted  byte  by 
byte  for  new  data,  starting  at  address.  The  current  contents  of  a  byte  are  displayed,  fol¬ 
lowed  by  a  period.  A  new  value  for  the  byte  can  be  entered  as  one  or  two  hexadecimal 
digits  (extra  characters  are  ignored),  or  the  contents  can  be  left  unchanged.  To  display  the 
next  byte,  the  user  presses  the  spacebar.  If  the  user  enters  a  minus  sign,  or  hyphen  charac¬ 
ter  (-),  instead  of  pressing  the  spacebar,  SYMDEB  backs  up  to  the  previous  byte.  A  maxi¬ 
mum  of  8  bytes  can  be  entered  on  each  input  line;  a  new  line  is  begun  each  time  an  8-byte 
boundary  is  crossed.  Data  entry  is  terminated  by  pressing  the  Enter  key  without  pressing 
the  spacebar  or  entering  any  data. 

Text  strings  can  be  used  only  as  part  of  the  list  parameter  in  an  EB  command  line;  they 
cannot  be  entered  in  response  to  an  address  prompt. 
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Examples 

To  store  the  byte  values  OOH,  ODH,  and  OAH  into  the  3  bytes  beginning  at  DS:1FB3H,  type 

-EB  1FB3  00  OD  OA  <Enter> 

To  store  the  string  MAIN  MENU  into  memory  beginning  at  address  ES:0C14H,  type 

-EB  ES:C14  "MAIN  MENU"  <Enter> 
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SYMDEB:  ED 

Enter  Doublewords 


Purpose 

Enters  hexadecimal  doubleword  values  into  memory. 

Syntax 

ED  address[value] 
where: 

address  is  the  first  memory  location  for  storage. 

value  is  a  doubleword  (32-bit)  hexadecimal  value. 

Description 

The  Enter  Doublewords  (ED)  command  enters  into  memory  32-bit  hexadecimal  double- 
word  values  in  the  form  of  FAR  memory  pointers  (offset  followed  by  segments  in  reverse 
byte  order).  Any  data  previously  stored  at  the  specified  locations  is  lost.  If  SYMDEB  dis¬ 
plays  an  error  message,  no  changes  are  made. 

The  address  parameter  specifies  the  first  memory  location  to  be  modified.  If  address  does 
not  include  a  segment,  SYMDEB  uses  DS. 

The  value  parameter  is  one  doubleword  value,  entered  as  two  l6-bit  hexadecimal  words 
separated  by  a  colon  character  (:).  Each  value  is  entered  in  the  form  segment:offset.  The 
offset  portion  is  stored  at  address,  and  the  segment  portion  is  stored  at  address'^2,  both  in 
reverse  byte  order.  For  example,  a  value  of  AABB:CCDDH  would  be  stored  in  memory  as 
DDH,  CCH,  BBH,  and  AAH,  starting  at  address.  Multiple  values  cannot  be  used  in  an  ED 
command  line;  SYMDEB  ignores  any  values  after  the  first  value. 

If  value  is  omitted  from  the  command  line,  SYMDEB  prompts  the  user  for  new  data,  start¬ 
ing  at  address.  The  current  contents  of  the  location  are  displayed,  followed  by  a  period. 
The  user  can  then  enter  a  new  doubleword  value  and  press  the  Enter  key  or  leave  the  con¬ 
tents  unchanged  by  pressing  the  Enter  key  alone,  which  also  terminates  the  ED  command. 
If  a  new  value  is  entered,  SYMDEB  increments  address  and  displays  the  next  doubleword 
value. 

Example 

To  store  the  doubleword  value  F000:1392H  at  the  address  DS:0200H,  type 

-ED  200  F000:1392  <Enter> 
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SYMDEB:  EL 

Enter  Long  Reals 


Purpose 

Enters  64-bit  floating-point  numbers  into  memory. 

Syntax 

EL  address{value] 
where: 

address  is  the  first  memory  location  for  storage. 
value  is  a  64-bit  floating-point  decimal  number. 

Description 

The  Enter  Long  Reals  (EL)  command  enters  into  memory  64-bit  floating-point  numbers 
in  decimal  format.  Any  data  previously  stored  at  the  specified  memory  locations  is  lost.  If 
SYMDEB  displays  an  error  message,  no  changes  are  made. 

The  address  parameter  specifies  the  first  byte  to  be  modified.  If  address  does  not  include 
a  segment,  SYMDEB  uses  DS. 

The  valm  parameter  is  a  floating-point  number  entered  in  decimal  radix,  with  or  without 
a  decimal  point  and/or  exponent.  Multiple  values  cannot  be  used  in  an  EL  command  line; 
SYMDEB  ignores  any  values  after  the  first  value. 

The  64-bit  floating-point  decimal  value  must  be  entered  in  the  form 

[+  \-]deciinaldigits[E{^  1  -]mantissd\ 

where: 

+ 1  -  is  the  sign  of  the  long  floating-point  value  or  the  mantissa. 

decimaldigits  is  a  decimal  number.  A  maximum  of  16  digits  is  allowed,  including  digits 
before  and  after  a  decimal  point. 

E  denotes  the  beginning  of  the  mantissa. 

mantissa  is  the  decimal  mantissa  value. 

If  value  is  omitted  from  the  command  line,  SYMDEB  prompts  the  user  for  new  data,  start¬ 
ing  at  address.  The  current  contents  of  the  location  are  displayed.  The  user  can  enter  a 
new  value  and  press  the  Enter  key  or  leave  the  contents  unchanged  by  pressing  the  Enter 
key  alone,  which  also  terminates  the  EL  command.  If  a  new  value  is  entered  and  the  Enter 
key  is  pressed,  SYMDEB  increments  address  and  displays  the  next  long  real  number. 
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Example 

To  store  an  approximation  of  the  value  pi  (jO  in  the  form  of  a  64-bit  floating-point  number 
at  address  DS:0020H,  type 

-EL  20  +0.3141592653589793E+1  <Enter> 

or 

-EL  20  3.141592653589793  <Enter> 
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SYMDEB:  ES 

Enter  Short  Reals 


Purpose 

Enters  32-bit  floating-point  numbers  into  memory. 

Syntax 

ES  address  [  value] 
where: 

address  is  the  first  memory  location  for  storage. 

value  is  a  32-bit  floating-point  decimal  number. 

Description 

The  Enter  Short  Reals  (ES)  command  enters  into  memory  32-bit  floating-point  numbers 
in  decimal  format.  Any  data  previously  stored  at  the  specified  locations  is  lost.  If  SYMDEB 
displays  an  error  message,  no  changes  are  made. 

The  address  parameter  specifies  the  first  byte  to  be  modified.  If  address  does  not  include 
a  segment,  SYMDEB  uses  DS. 

The  value  parameter  is  a  floating-point  number  entered  in  decimal  radix,  with  or  without 
a  decimal  point  and/or  exponent.  Multiple  values  cannot  be  used  in  an  ES  command  line; 
SYMDEB  ignores  any  values  after  the  first  value. 

The  32-bit  floating-point  decimal  value  must  be  entered  in  the  form 

[+  \-]decimaldigits[^[+  \-]mantissa] 

where: 

+ 1  -  is  the  sign  of  the  short  floating-point  value  or  the  mantissa. 

decimaldigits  is  a  decimal  number.  A  maximum  of  l6  digits  is  allowed,  including  digits 
before  and  after  a  decimal  point. 

E  denotes  the  beginning  of  the  mantissa. 

mantissa  is  the  decimal  mantissa  value. 

Note:  For  short  floating-point  values,  the  last  nine  decimaldigits  are  not  significant.  This 
can  be  demonstrated  by  using  the  Display  Short  Reals  (DS)  command  to  check  the  new 
value  in  memory. 

If  value  is  omitted  from  the  command  line,  SYMDEB  prompts  the  user  for  new  data,  start¬ 
ing  at  address.  The  current  contents  of  the  location  are  displayed.  The  user  can  then  enter 
a  new  value  and  press  the  Enter  key  or  leave  the  contents  unchanged  by  pressing  the 
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Enter  key  alone,  which  also  terminates  the  ES  command.  If  a  new  value  is  entered  and  the 
Enter  key  is  pressed,  SYMDEB  increments  address  and  displays  the  next  short  floating¬ 
point  number. 

Example 

To  store  an  approximation  of  the  value  pi  (tc)  in  the  form  of  a  32-bit  floating-point  number 
at  address  DS:0020H,  type 

-ES  20  +0.31415927E+1  <Enter> 

or 

-ES  20  3.1415927  <Enter> 
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SYMDEB:  ET 

Enter  10-Byte  Reals 


Purpose 

Enters  10-byte  (80-bit)  floating-point  numbers  into  memory. 

Syntax 

ET  address[value] 
where: 

address  is  the  first  memory  location  for  storage. 

value  is  an  80-bit  floating-point  decimal  number. 

Description 

The  Enter  10-Byte  Reals  (ET)  command  enters  into  memory  10-byte  (80-bit)  floating-point 
numbers  in  decimal  format.  Any  data  previously  stored  at  the  specified  locations  is  lost.  If 
SYMDEB  displays  an  error  message,  no  changes  are  made.  (This  10-byte  format  is  ordinar¬ 
ily  used  by  the  Intel  8087  math  coprocessor  only  for  intermediate  results  during  chained 
floating-point  calculations.) 

The  address  parameter  specifies  the  first  memory  location  to  be  modified.  If  address  does 
not  include  a  segment,  SYMDEB  uses  DS. 

The  value  parameter  is  a  floating-point  number  entered  in  decimal  radix,  with  or  without 
a  decimal  point  and/or  exponent.  Multiple  values  cannot  be  used  in  an  ET  command  line; 
SYMDEB  ignores  any  values  after  the  first  value. 

The  10-byte  floating-point  decimal  value  must  be  entered  in  the  form 

[+  \-]deciinaldigits[E[^ \-]mantissa] 

where: 

+ 1  -  is  the  sign  of  the  10-byte  floating-point  value  or  the  mantissa. 

decimaldigits  is  a  decimal  number.  A  maximum  of  16  digits  is  allowed,  including  digits 
before  and  after  a  decimal  point. 

E  denotes  the  beginning  of  the  mantissa. 

mantissa  is  the  decimal  mantissa  value. 

If  value  is  omitted  from  the  command,  SYMDEB  prompts  the  user  for  new  data,  starting  at 
address.  The  current  contents  are  displayed.  The  user  can  enter  a  new  value  and  press  the 
Enter  key  or  leave  the  contents  unchanged  by  pressing  the  Enter  key  alone,  which  also  ter¬ 
minates  the  ET  command.  If  a  new  value  is  entered  and  the  Enter  key  is  pressed,  SYMDEB 
increments  address  and  displays  the  next  10-byte  floating-point  number. 
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Example 

To  store  an  approximation  of  the  value  pi  00  in  the  form  of  an  80-bit  floating-point  num¬ 
ber  at  address  DS:0020H,  type 

-ET  20  +0.31415926535897932384E+1  <Enter> 

or 

-ET  20  3.1415926535897932384  <Enter> 
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SYMDEB:  EW 

Enter  Words 


Purpose 

Enters  word  values  into  memory. 

Syntax 

EW  address  [value] 
where: 

address  is  the  first  memory  location  for  storage. 
value  is  a  word  (l6-bit)  hexadecimal  value. 

Description 

The  Enter  Words  (EW)  command  enters  into  memory  l6-bit  hexadecimal  word  values. 

Any  data  previously  stored  at  the  specified  locations  is  lost.  If  SYMDEB  displays  an  error 
message,  no  changes  are  made. 

The  address  parameter  specifies  the  first  memory  location  to  be  modified.  If  address  does 
not  include  a  segment,  SYMDEB  uses  DS. 

The  value  parameter  is  one  word  value  in  the  range  0  through  FFFFH.  The  value  is  stored 
in  reverse  byte  order.  For  example,  a  value  of  AABBH  would  be  stored  in  memory  as  BBH 
and  AAH,  starting  at  address.  Multiple  values  cannot  be  used  in  an  EW  command  line; 
SYMDEB  ignores  any  values  after  the  first  value. 

If  value  is  omitted  from  the  command  line,  SYMDEB  prompts  the  user  word  by  word  for 
new  data,  starting  at  address.  The  current  contents  are  displayed,  followed  by  a  period. 
The  user  can  enter  a  new  word  value  as  one  to  four  hexadecimal  digits  and  press  the  Enter 
key  or  leave  the  contents  unchanged  by  pressing  the  Enter  key  alone,  which  also  termi¬ 
nates  the  EW  command.  If  a  new  value  is  entered,  SYMDEB  increments  address  and  dis¬ 
plays  the  next  word  value. 

Example 

To  store  the  word  value  1355H  at  the  address  DS:1C00H,  type 

-EW  ICOO  1355  <Enter> 
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SYMDEB:  F 

Fill  Memory 


Purpose 

Stores  a  repetitive  data  pattern  into  an  area  of  memory. 

Syntax 

F  range  list 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 
of  memory  to  be  filled. 

list  is  the  data  to  be  used  to  fill  memory. 

Description 

The  Fill  Memory  (F)  command  fills  an  area  of  memory  with  the  data  from  a  list.  The  data 
can  be  entered  in  either  hexadecimal  or  ASCII  format.  Any  data  previously  stored  at  the 
specified  locations  is  lost.  If  SYMDEB  displays  an  error  message,  no  changes  are  made. 

The  range  parameter  specifies  the  starting  and  ending  addresses  or  the  starting  address 
and  hexadecimal  length  in  bytes  of  the  area  of  memory  to  be  filled.  If  range  does  not  in¬ 
clude  an  explicit  segment,  SYMDEB  uses  DS. 

The  list  parameter  is  one  or  more  hexadecimal  byte  values  and/or  strings,  separated  by 
spaces,  commas,  or  tab  characters.  Strings  must  be  enclosed  in  single  or  double  quotation 
marks,  and  case  is  significant  within  a  string. 

If  the  area  to  be  filled  is  larger  than  the  data  list,  the  list  is  repeated  as  often  as  necessary  to 
fill  the  area.  If  the  data  list  is  longer  than  the  area  of  memory  to  be  filled,  the  list  is  trun¬ 
cated  to  fit. 

Examples 

To  fill  the  area  of  memory  from  DSiOBlOH  through  DS;0B4FH  with  the  value  0E8H,  type 

-F  BIO  B4F  E8  <Enter> 

or 

-F  BIO  L40  E8  <Enter> 

To  fill  the  16  bytes  of  memory  beginning  at  address  CS:1FA0H  by  replicating  the  2-byte 
sequence  ODH  OAH,  type 

-F  CS:1FA0  1 FAF  OD  OA  <Enter> 

or 

-F  CSilFAO  LIO  OD  OA  <Enter> 
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To  fill  the  area  of  memory  from  ES:0B00H  through  ESiOBFFH  by  replicating  the  text  string 
BUFFER,  type 

-F  ESrBOO  BFF  "BUFFER"  <Enter> 

or 

-F  ES:B00  L100  "BUFFER"  <Enter> 
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SYIdDEB:  G 

Go 


Purpose 

Transfers  execution  control  from  SYMDEB  to  the  target  program  being  debugged. 

Syntax 

G[= address]  [breakO[ . . .  break9]] 
where: 

address  is  the  location  at  which  to  begin  execution. 

breakO  . . .  break9  specify  from  1  to  10  breakpoints. 

Description 

The  Go  (G)  command  transfers  control  from  SYMDEB  to  the  target  program.  If  no  break¬ 
points  are  set,  the  program  will  execute  until  it  crashes  or  until  it  reaches  a  normal  ter¬ 
mination,  in  which  case  the  message  Program  terminated  normally  is  displayed  and 
control  returns  to  SYMDEB.  (After  this  message  has  been  displayed,  it  may  be  necessary 
to  reload  the  program  before  it  can  be  executed  again.) 

The  address  parameter  can  be  any  location  in  memory.  If  no  segment  is  specified, 
SYMDEB  uses  the  target  program’s  CS  register.  If  address  is  omitted,  SYMDEB  transfers  to 
the  current  address  in  the  target  program’s  CS:IP  registers.  An  equal  sign  (=)  must  precede 
address  to  distinguish  it  from  the  breakpoints  breakO  . . .  break9. 

The  parameters  breakO  . . .  break9  specify  from  1  to  10  breakpoints  that  can  be  set  as  part 
of  the  G  command.  Breakpoints  can  be  placed  in  any  order,  because  execution  stops  at  the 
first  breakpoint  address  encountered,  regardless  of  the  position  of  that  breakpoint  in  the 
list.  Each  of  the  breakpoint  addresses  must  contain  the  first  byte  of  an  8086  opcode. 
SYMDEB  installs  breakpoints  by  replacing  the  first  byte  of  the  machine  instruction  at  each 
breakpoint  address  with  an  Interrupt  03H  instruction  (opcode  OCCH).  If  the  program  en¬ 
counters  a  breakpoint,  program  execution  is  suspended  and  control  returns  to  SYMDEB. 
SYMDEB  then  restores  the  original  machine  code  in  the  breakpoint  locations,  displays  the 
contents  of  the  current  registers  and  flags  and  the  instruction  pointed  to  by  CS:IP,  and 
issues  the  standard  SYMDEB  prompt.  If  the  target  program  executes  to  completion  and  ter¬ 
minates  without  encountering  any  of  the  breakpoints  or  is  halted  by  some  means  other 
than  a  breakpoint,  the  Interrupt  03H  instructions  are  not  replaced  with  the  original 
machine  code  and  the  Load  File  or  Sectors  (L)  command  must  be  used  to  reload  the  origi¬ 
nal  program. 

The  G  command  requires  that  the  target  program’s  SS:SP  registers  point  to  a  valid  stack 
that  has  at  least  6  bytes  of  stack  space  available.  When  the  G  command  is  executed,  it 
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pushes  the  target  program’s  flags  and  CS  and  IP  registers  onto  the  stack  and  then  transfers 
control  to  the  program  with  an  IRET  instruction.  Thus,  if  the  target  program’s  stack  is  not 
valid  or  is  too  small,  the  system  may  crash. 

The  G  command  also  recognizes  any  sticky  breakpoints  set  with  the  Set  Breakpoint  (BP) 
command.  These  sticky  breakpoints  are  not  counted  as  part  of  the  transient  breakpoints 
specified  in  the  G  command  line  and  are  not  removed  after  a  breakpoint  has  been 
encountered. 

Examples 

To  begin  execution  of  the  program  in  SYMDEB’s  buffer  at  location  CSrllOAH,  setting 
breakpoints  at  CS:12FCH  and  CS:1303H,  type 

-G  =11 OA  12FC  1303  <Enter> 

To  resume  execution  of  the  program  following  a  breakpoint,  type 

“G  <Enter> 

To  begin  execution  at  the  label  main,  setting  breakpoints  at  the  procedures  fopenO  and 
printfO,  type 

-G  =_main  _fopen  _printf  <Enter> 

Messages 

Program  terminated  normally 

The  program  being  debugged  executed  successfully  without  encountering  any  break¬ 
points  and  performed  a  normal  termination  with  Interrupt  20H,  Interrupt  21H  Function 
OOH,  or  Interrupt  21H  Function  4CH.  If  any  breakpoints  were  set,  the  original  program 
should  be  reloaded  with  the  Load  File  or  Sectors  (L)  command. 

Too  many  breakpoints! 

More  than  10  breakpoints  were  specified  in  a  Go  (G)  command.  Enter  the  command  again 
with  10  or  fewer  breakpoints. 
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Perform  Hexadecimal  Arithmetic 

Purpose 

Displays  the  sum  and  difference  of  two  hexadecimal  numbers. 

Syntax 

H  valuel  value2 
where: 

valuel  and  value2  are  any  two  hexadecimal  numbers  in  the  range  0  through  FFFFH. 

Description 

The  Perform  Hexadecimal  Arithmetic  (H)  command  displays  the  sum  and  difference  of 
two  l6-bit  hexadecimal  numbers — that  is,  the  result  of  the  operations  valuel+value2  and 
valuel-value2.  If  value2  is  greater  than  valuel,  SYMDEB  displays  their  difference  as  a 
two’s  complement  hexadecimal  number.  This  command  is  convenient  for  performing 
quick  calculations  of  addresses  and  other  values  during  an  interactive  debugging  session. 

Examples 

To  display  the  sum  and  difference  of  the  values  4B03H  and  104H,  type 

4B03  104  <Enter> 

This  produces  the  following  display: 

4C07  49FF 

If  the  addition  produces  an  overflow,  the  four  least  significant  digits  are  displayed.  For 
example,  the  command  line 

_H  FFFF  2  <Enter> 

produces  the  following  display: 

0001  FFFD 

If  value2  is  greater  than  valuel,  the  difference  is  displayed  in  two’s  complement  form.  For 
example,  the  command  line 

-H  1  2  <Enter> 

produces  the  following  display: 

0003  FFFF 
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SYMDEB:  I 

Input  from  Port 


Purpose 

Reads  and  displays  1  byte  from  an  input/output  (I/O)  port. 

Syntax 

I  port 
where: 

port  is  a  16-bit  I/O  port  address  in  the  range  0  through  FFFFH. 

Description 

The  Input  from  Port  (I)  command  performs  a  read  operation  on  the  specified  I/O  port 
address  and  displays  the  data  as  a  two-digit  hexadecimal  number. 

Warning:  This  command  must  be  used  with  caution  because  it  involves  direct  access  to 
the  computer  hardware  and  no  error  checking  is  performed.  Input  operations  directed  to 
the  ports  assigned  to  some  peripheral  device  controllers  may  interfere  with  the  proper 
operation  of  the  system.  If  no  device  has  been  assigned  to  the  specified  I/O  port  or  if  the 
port  is  write-only,  the  value  that  will  be  displayed  by  an  I  command  is  unpredictable. 

Example 

To  read  and  display  the  contents  of  I/O  port  lOAH,  type 

-I  1 OA  <Enter> 

An  example  of  the  result  of  this  command  is 

FF 
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SYMDEB:  K 

Perform  Stack  Trace 


Purpose 

Displays  the  current  stack  frame. 

Syntax 

K  [number] 
where: 

number  is  the  number  of  parameters  supplied  to  the  current  procedure. 

Description 

The  Perform  Stack  Trace  (K)  command  displays  the  contents  of  the  current  stack  frame. 
The  first  line  of  the  display  shows  the  name  of  the  current  procedure,  parameters  to  the 
procedure,  and  the  filename  and  line  number  of  the  call  to  the  procedure.  The  subsequent 
lines  trace  the  flow  of  execution  that  led  to  the  current  procedure. 

In  cases  where  SYMDEB  cannot  determine  the  number  of  parameters  for  a  procedure  by 
inspection  of  the  stack  frame  (for  example,  if  the  number  of  parameters  sent  to  a  proce¬ 
dure  varies),  the  number  option  can  be  used  in  the  command  to  force  the  display  of  one 
or  more  parameters. 

The  K  command  can  be  used  only  on  procedures  that  follow  the  calling  conventions  used 
by  Microsoft  high-level-language  compilers. 

Examples 

Assume  that  a  breakpoint  has  been  set  within  the  C  library  printfO  routine,  that  the 
breakpoint  has  been  reached,  and  that  the  SYMDEB  prompt  has  reappeared.  The 
command 

-K  <Enter> 

produces  the  following  output: 

_TEXT:_printf (00D4, 0000, 0000)  from  .dump.C:108 
_TEXT:_dump_para (0000,  0000, 0FB8)  from  . dump. C; 92 
_TEXT:_dump_rec (0FB8,  0001 , 0000, 0000)  from  . dump. C: 61 
_TEXT:_jnain  (?) 

In  this  example,  the  breakpointed  procedure  printfO  was  called  by  the  routine 
dump^paraO  with  three  parameters.  Dump_^raO  was  called  by  dump^recO,  which  in 
turn  was  called  by  mainO.  Because  SYMDEB  cannot  determine  the  depth  of  the  stack 
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frame  for  the  routine  main(X  it  displays  no  parameters  for  it.  The  display  of  at  least  two 
parameters  for  every  procedure  can  be  forced  by  the  command 

-K  2  <Enter> 

which  produces  the  following  example  display: 

__TEXT:_printf  (00D4, 0000,  0000)  from  .dump.C:108 
_TEXT:_dump_para (0000, 0000, 0FB8)  from  . dump. C: 92 
_TEXT:_dump_rec (0FB8,  0001 , 0000, 0000)  from  . dump. C: 61 
_TEXT:_main (0002, 1044) 

From  a  knowledge  of  C  conventions,  it  follows  that  the  first  parameter  for  mainO  is  urge, 
or  the  number  of  tokens  in  the  command  line  that  invoked  the  program  being  debugged; 
the  second  parameter  is  the  offset  within  DGROUP  of  argv,  or  an  array  of  pointers  to 
each  token. 
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SYMDEB:  L 

Load  File  or  Sectors 


Purpose 

Loads  a  file  or  individual  sectors  from  a  disk. 

Syntax 

L  [address] 
or 

L  address  drive  start  number 
where: 

address  is  the  starting  address  in  memory  that  data  read  from  a  disk  is  placed  into. 

drive  is  the  decimal  number  (0-3)  of  the  disk  to  read  (0  =  drive  A,  1  =  drive  B, 

2  =  drive  C,  3=  drive  D). 

start  is  the  hexadecimal  number  of  the  first  sector  to  load  (0-FFFFH). 
number  is  the  hexadecimal  number  of  consecutive  sectors  to  load  (0-FFFFH). 

Description 

The  Load  File  or  Sectors  (L)  command  loads  a  file  or  individual  sectors  from  a  disk. 

When  the  L  command  is  entered  without  parameters  or  with  an  address  alone,  the  file 
specified  in  the  SYMDEB  command  line  or  with  the  most  recent  Name  File  or  Command- 
Tail  Parameters  (N)  command  is  loaded  from  the  disk  into  memory.  If  no  segment  is  speci¬ 
fied  in  address,  SYMDEB  uses  CS.  If  the  file’s  extension  is  .EXE,  the  file  is  placed  in 
SYMDEB’s  target  program  buffer  at  the  load  address  specified  in  the  .EXE  file’s  header;  if 
the  file’s  extension  is  .COM,  the  file  is  loaded  at  offset  lOOH.  (If  for  some  reason  an  address 
is  entered  for  a  .EXE  or  .COM  file  and  the  address  is  anything  but  lOOH,  an  error  message  is 
displayed;  if  the  address  is  lOOH,  it  will  be  ignored.)  If  the  file  has  a  .HEX  extension,  the 
.HEX  file’s  starting  address  is  added  to  address  before  loading  the  file.  If  address  is  not 
specified,  the  .HEX  file  is  placed  at  its  own  starting  address.  The  length  of  the  file  or,  in 
the  case  of  a  .EXE  file,  the  actual  length  of  the  program  (the  length  of  the  file  minus  the 
header)  is  placed  in  the  target  program’s  BX  and  CX  registers,  with  the  most  significant  l6 
bits  in  register  BX. 

The  L  command  can  also  be  used  to  bypass  the  MS-DOS  file  system  and  obtain  direct 
access  to  logical  sectors  on  the  disk.  The  memory  address  {address),  disk  drive  number 
{drive),  starting  logical  sector  number  {start),  and  number  of  sectors  to  read  {number) 
must  all  be  specified  in  the  command  line. 

Note:  The  L  command  should  not  be  used  to  access  logical  sectors  on  network  drives. 
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Examples 

To  load  the  file  specified  in  the  SYMDEB  command  line  or  in  the  most  recent  N  command 
into  SYMDEB’s  target  program  buffer,  type 

-L  <Enter> 

To  load  eight  sectors  from  drive  B,  starting  at  logical  sector  0,  to  memory  location  CS:0100H 
in  SYMDEB’s  memory  buffer,  type 

-L  100  1  08  <Enter> 

Messages 

Disk  error  reading  disk  X 

A  hardware-related  disk  error,  such  as  a  checksum  error  or  seek  incomplete,  was  encoun¬ 
tered  during  the  execution  of  an  L  command. 

File  not  found 

The  file  specified  in  the  most  recent  N  command  cannot  be  found. 
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Move  (Copy)  Data 


Purpose 

Copies  the  contents  of  one  area  of  memory  to  another. 

Syntax 

M  range  address 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  length 

of  the  area  of  memory  to  be  copied. 
address  is  the  first  byte  of  the  destination  of  the  copy  operation. 

Description 

The  Move  (Copy)  Data  (M)  command  copies  data  from  one  location  in  memory  to  another 
without  altering  the  data  in  the  original  location.  If  the  source  and  destination  areas  over¬ 
lap,  the  data  is  copied  in  the  correct  order  so  that  the  resulting  copy  is  correct;  the  data  in 
the  original  location  is  changed  only  when  the  two  areas  overlap. 

The  range  parameter  specifies  the  starting  and  ending  addresses  or  the  starting  address 
and  length  of  the  memory  to  be  copied.  The  address  parameter  is  the  first  byte  in  which 
the  copy  will  be  placed.  If  range  does  not  contain  an  explicit  segment,  SYMDEB  uses  DS; 
if  address  does  not  contain  a  segment,  SYMDEB  uses  the  same  segment  used  for  range. 

Example 

To  copy  the  data  in  locations  DS:0800H  through  DS:08FFH  to  locations  DS:0900H  through 
DS;09FFH,  type 

-M  800  8FF  900  <Enter> 

or 

-M  800  LI  00  900  <Enter> 
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SYMDEB:  N 

Name  File  or  Command-Tail  Parameters 


Purpose 

Inserts  parameters  into  the  simulated  program  segment  prefix  (PSP). 

Syntax 

N  parameter[  parameter. . .  ] 
where: 

parameter  is  a  filename  or  switch  to  be  placed  into  the  simulated  PSP. 

Description 

The  Name  File  or  Command-Tail  Parameters  (N)  command  is  used  to  enter  one  or  more 
parameters  into  the  simulated  PSP  that  is  built  at  the  base  of  the  buffer  holding  the  pro¬ 
gram  to  be  debugged.  The  N  command  can  also  be  used  before  the  Load  File  or  Sectors  (L) 
and  Write  File  or  Sectors  (W)  commands  to  name  a  file  to  be  read  from  a  disk  or  written 
to  a  disk. 

The  count  of  the  characters  following  the  N  command  is  placed  at  DS:0080H  in  the  simu¬ 
lated  PSP  and  the  characters  themselves  are  copied  into  the  PSP  starting  at  DS:0081H.  The 
string  is  terminated  by  a  carriage  return  (ODH),  which  is  not  included  in  the  count.  If  the 
second  and  third  parameters  follow  the  naming  conventions  for  MS-DOS  files,  they  are 
parsed  into  the  default  file  control  blocks  (FCBs)  in  the  simulated  PSP,  at  offset  5CH  and 
offset  6CH,  respectively.  Note  that  this  is  different  from  the  N  command  in  DEBUG,  which 
loads  the  first  and  second  parameters  into  the  default  FCBs.  (Switches  and  other  filenames 
specified  as  parameters  are  stored  in  the  PSP  starting  at  offset  81H  along  with  the  rest  of 
the  command  line  but  are  not  parsed  into  the  default  FCBs.) 

If  the  N  command  line  contains  only  one  filename,  any  parameters  placed  in  the  default 
FCBs  by  a  previous  N  command  are  destroyed.  If  the  drive  included  with  the  second  file¬ 
name  parameter  is  invalid,  the  AL  register  is  set  to  OFFH.  If  the  drive  included  with  the 
third  filename  parameter  is  invalid,  the  AH  register  is  set  to  OFFH.  The  existence  of  a  file 
specified  with  the  N  command  is  not  verified  imtil  it  is  loaded  with  the  L  command. 

The  filename  at  DS:0081H  specifies  the  file  that  is  read  or  written  by  a  subsequent  L  or  W 
command. 

Example 

Assume  that  SYMDEB  was  started  without  specifying  the  name  of  a  target  program  in  the 
command  line.  To  load  the  program  CLEAN.COM  for  execution  under  the  control  of 
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SYMDEB  and  include  the  parameter  MYFILE.DAT  in  the  simulated  PSP’s  command  tail 
and  FCB,  use  the  N  and  L  commands  together  as  follows: 

-N  CLEAN.COM  MYFILE.DAT  <Enter> 

-L  <Enter> 

To  execute  the  program  CLEAN.COM,  type 

-G  <Enter> 

The  net  effect  is  the  same  as  if  the  CLEAN.COM  program  had  been  run  from  the  MS-DOS 
command  level  with  the  command  line 

OCLEAN  MYFILE.DAT  <Enter> 

except  that  the  program  is  executing  under  the  control  of  SYMDEB  and  within  SYMDEB’s 
memory  buffer. 
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SYMDEB:  O 

Output  to  Port 


Purpose 

Writes  1  byte  to  an  input/output  (I/O)  port. 

Syntax 

O  port  byte 
where: 

port  is  a  l6-bit  I/O  port  address  in  the  range  0  through  FFFFH. 

byte  is  a  value  to  be  written  to  the  I/O  port  (O-OFFH). 

Description 

The  Output  to  Port  (O)  command  writes  1  byte  of  data  to  the  specified  I/O  port  address. 
The  data  value  must  be  in  the  range  OOH  through  OFFH. 

Warning:  This  command  must  be  used  with  caution  because  it  involves  direct  access  to 
the  computer  hardware  and  no  error  checking  is  performed.  Attempts  to  write  to  some 
port  addresses,  such  as  those  for  ports  connected  to  peripheral  device  controllers,  timers, 
or  the  system’s  interrupt  controller,  may  cause  the  system  to  crash  or  may  even  result  in 
damage  to  data  stored  on  disk. 

Example 

To  write  the  value  C8H  to  I/O  port  lOAH,  type 

-0  10A  C8  <Enter> 
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SYMDEB:  P 

Proceed  Through  Loop  or  Subroutine 


Purpose 

Executes  a  loop,  string  instruction,  software  interrupt,  or  subroutine  to  completion. 

Syntax 

V[^address]  [number] 
where: 

address  is  the  location  of  the  first  instruction  to  be  executed. 
number  is  the  number  of  instructions  to  execute. 

Description 

The  Proceed  Through  Loop  or  Subroutine  (P)  command  transfers  control  to  the  target  pro¬ 
gram.  The  program  executes  without  interruption  until  the  loop,  repeated  string  instruc¬ 
tion,  software  interrupt,  or  subroutine  call  at  address  is  completed  or  until  the  specified 
number  of  machine  instructions  have  been  executed.  Control  then  returns  to  SYMDEB 
and  the  current  contents  of  the  target  program’s  registers  and  flags  are  displayed. 

Warning:  The  P  command  should  not  be  used  to  execute  any  instruction  that  changes  the 
contents  of  the  Intel  8259  interrupt  mask  (ports  20H  and  21H  on  the  IBM  PC  and  compat¬ 
ibles)  and  cannot  be  used  to  trace  through  ROM.  Use  the  Go  (G)  command  instead. 

If  the  address  parameter  does  not  contain  a  segment,  SYMDEB  uses  the  target  program’s 
CS  register;  if  address  is  omitted,  execution  begins  at  the  current  address  specified  by  the 
target’s  CS:IP  registers.  The  address  parameter  must  be  preceded  by  an  equal  sign  (=)  to 
distinguish  it  from  number 

The  number  parameter  specifies  the  number  of  instructions  to  be  executed  before  control 
returns  to  SYMDEB.  If  number  is  omitted,  one  instruction  is  executed. 

When  the  Enable  Source  Display  Mode  (S+)  command  is  selected,  the  P  command  oper¬ 
ates  directly  on  source-code  lines,  passing  over  function  or  procedure  calls.  (The  S+  com¬ 
mand  can  be  used  only  with  programs  created  by  high-level-language  compilers  that 
insert  line-number  information  into  object  modules.) 

When  source  display  mode  is  disabled  with  the  S-  command  or  when  the  program  being 
debugged  does  not  have  a  .SYM  file  or  has  been  created  with  the  Microsoft  Macro  Assem¬ 
bler  (MASM)  or  with  a  compiler  that  does  not  support  line  numbers  in  relocatable  object 
modules,  the  P  command  behaves  like  the  Trace  Program  Execution  (T)  command  except 
that  when  P  encounters  a  loop,  repeated  string  instruction,  software  interrupt,  or  sub¬ 
routine  call,  it  executes  it  to  completion  and  then  returns  to  the  instruction  following  the 
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call.  For  example,  if  the  user  wants  to  trace  the  first  three  instructions  in  a  program  and  if 
the  second  instruction  is  a  subroutine  call,  a  P3  command  executes  the  first  instruction, 
goes  to  the  second  instruction,  identifies  it  as  a  CALL  instruction,  jumps  to  the  subroutine 
and  executes  the  entire  subroutine,  comes  back  and  executes  the  third  instruction,  and 
then  stops.  A  T3  command,  on  the  other  hand,  executes  the  first  instruction,  executes  the 
second,  executes  the  first  instruction  of  the  subroutine  as  its  third  instruction,  and  then 
stops.  If  the  instruction  at  address  is  not  a  loop,  repeated  string  instruction,  software  inter¬ 
rupt,  or  subroutine  call,  the  P  command  functions  just  like  the  T  command.  After  each 
instruction  is  executed,  SYMDEB  displays  the  current  contents  of  the  target  program’s 
registers  and  flags  and  the  next  instruction  to  be  executed. 

Examples 

Assume  that  the  program  being  debugged  was  compiled  with  Microsoft  C,  a  .SYM  file  was 
loaded  with  the  executable  program  to  provide  line-number  information,  and  source-code 
display  has  been  enabled  with  the  S+  command.  To  execute  the  machine  instructions  cor¬ 
responding  to  the  next  four  lines  of  source  code,  type 

-P  4  <Enter> 

Assume  that  the  target  program  was  created  with  MASM  and  location  CS:143FH  contains  a 
CALL  instruction.  To  execute  the  subroutine  that  is  the  destination  of  CALL  at  full  speed 
and  then  return  control  to  SYMDEB,  type 

-P  =143F  <Enter> 
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SYMDEB:  Q 

Quit 


Purpose 

Ends  a  SYMDEB  session. 

Syntax 

Q 

Description 

The  Quit  (Q)  command  terminates  the  SYMDEB  program  and  returns  control  to  MS-DOS 
or  the  command  shell  that  invoked  SYMDEB.  Any  changes  made  to  a  program  or  other  file 
that  were  not  previously  saved  to  disk  with  the  Write  File  or  Sectors  (W)  command  are  lost 
when  the  Q  command  is  used. 

Example 

To  exit  SYMDEB,  type 

-Q  <Enter> 
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Display  or  Modify  Registers 


Purpose 

Displays  one  or  all  registers  and  allows  a  register  to  be  modified. 

Syntax 

R 

or 

R  register[[=^]  valtAe] 
where: 

register  is  the  two-character  name  of  an  Intel  8086/8088  register  from  the  following 
list: 

AX  BX  CX  DX  SP  BP  SI  DI 
DS  ES  SS  CS  IP  PC 

or  the  character  F,  to  indicate  the  CPU  flags. 

=  is  an  optional  equal  sign  preceding  value. 

value  is  a  l6-bit  integer  (0-FFFFH)  that  will  be  assigned  to  the  specified  register. 

Description 

The  Display  or  Modify  Registers  (R)  command  allows  the  target  program’s  register  con¬ 
tents  and  CPU  flags  to  be  displayed  and  modified. 

If  R  is  entered  without  a  register  parameter,  the  current  contents  of  all  registers  and  CPU 
flags  are  displayed,  followed  by  a  disassembly  of  the  machine  instruction  currently 
pointed  to  by  the  target  program’s  CS:IP  registers. 

A  register  can  be  assigned  a  new  value  in  a  single  command  by  entering  both  register  and 
value  parameters,  optionally  separated  by  an  equal  sign  (=).  If  a  register  is  named  but  no 
value  is  supplied,  SYMDEB  displays  the  current  contents  of  the  specified  register  and  then 
prompts  with  a  colon  character  (:)  for  a  new  value  to  be  placed  in  the  register.  The  user 
can  enter  the  value  in  any  valid  radix  or  as  an  expression  and  then  press  the  Enter  key.  If 
no  radix  is  appended  to  the  new  value,  hexadecimal  is  assumed.  If  the  user  presses  the  En¬ 
ter  key  alone  in  response  to  the  prompt,  no  changes  are  made  to  the  register  contents. 

Note:  The  PC  register  name  is  not  supported  properly  in  some  versions  of  SYMDEB,  so  the 
IP  register  name  should  always  be  used  instead. 
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Flag  Name 

Value  If  Set  (1) 

Value  If  dear  (0) 

Overflow 

OV  (Overflow) 

NV  (No  Overflow) 

Direction 

DN  (Down) 

UP  (Up) 

Interrupt 

El  (Enabled) 

DI  (Disabled) 

Sign 

NG  (Minus) 

PL  (Plus) 

Zero 

ZR  (Zero) 

NZ  (Not  Zero) 

Aux  Carry 

AC  (Aux  Carry) 

NA  (No  Aux  Carry) 

Parity 

PE  (Even) 

PO  (Odd) 

Carry 

CY  (Carry) 

NC  (No  Carry) 

After  displaying  the  current  flag  values,  SYMDEB  again  displays  its  prompt  (-).  Any  or  all 
of  the  individual  flags  can  then  be  altered  by  typing  one  or  more  two-character  flag  codes 
(in  any  order  and  optionally  separated  by  spaces)  from  the  list  above  and  then  pressing 
the  Enter  key.  If  the  user  responds  to  the  prompt  by  pressing  the  Enter  key  without  enter¬ 
ing  any  codes,  no  changes  are  made  to  the  status  of  the  flags. 

Examples 

To  display  the  current  contents  of  the  target  program's  CPU  registers  and  flags,  followed 
by  the  disassembled  mnemonic  for  the  next  instruction  to  be  executed  (pointed  to  by 
CS:IP),  type 

-R  <Enter> 

This  produces  the  following  display: 

AX=0000  BX=0000  CX=00A1  DX=0000  SP=FFFE  BP=0000  SI=0000  DI=0000 

DS=19A5  ES=19A5  SS=1 9A5  CS=1 9A5  IP=0100  NV  UP  El  PL  NZ  NA  PO  NC 

19A5:0100  BF8000  MOV  DI,0080 

If  the  source  display  mode  is  enabled,  the  R  command  displays  the  following: 

AX=0000  BX=1044  CX=0000  DX=0102  SP=103C  BP=0000  SI=00EA  DI=115E 

DS=2143  ES=2143  SS=2143  CS=1F6E  IP=0010  NV  UP  El  PL  ZR  NA  PE  NC 

32:  int  argc; 

_TEXT:_jnain: 

1F6E:0010  55  PUSH  BP  ;BR0 

This  format  includes  the  source  code  that  corresponds  to  the  next  instruction  to  be 
executed. 

To  set  the  contents  of  register  AX  to  FFFFH  without  displaying  its  current  value,  type 

-R  AX=FFFF  <Enter> 

or 

-R  AX  -1  <Enter> 
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To  display  the  current  value  of  the  target  program’s  BX  register,  type 

_R  BX  <Enter> 

If  BX  contains  200H,  for  example,  SYMDEB  displays  that  value  and  then  issues  a  prompt  in 
the  form  of  a  colon: 

BX  0200 

The  contents  of  BX  can  then  be  altered  by  typing  a  new  value  and  pressing  the  Enter  key, 
or  the  contents  can  be  left  unchanged  by  pressing  the  Enter  key  alone. 

To  set  the  direction  and  carry  flags,  first  type 

_R  F  <Enter> 

SYMDEB  displays  the  current  flag  values,  followed  by  a  prompt  in  the  form  of  a  hyphen 
character  (-).  For  example: 

NV  UP  El  PL  NZ  NA  PO  NC  - 

The  direction  and  carry  flags  can  then  be  set  by  entering 

_DN  CY  <Enter> 

on  the  same  line  as  the  prompt. 

Messages 

Bad  Flag! 

An  invalid  code  for  a  CPU  flag  was  entered. 

Bad  Register! 

An  invalid  register  name  was  entered. 

Double  Flag! 

Two  values  for  the  same  CPU  flag  were  entered  in  the  same  command. 
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Search  Memory 


Purpose 

Searches  memory  for  a  pattern  of  one  or  more  bytes. 

Syntax 

S  range  list 
where: 

range  is  the  starting  and  ending  address  or  the  starting  address  and  length  in  bytes  of 
the  area  to  be  searched. 

list  is  one  or  more  byte  values  or  a  string  to  be  searched  for. 

Description 

The  Search  Memory  (S)  command  searches  a  designated  range  of  memory  for  a  sequence 
of  byte  values  or  text  strings  and  displays  the  starting  address  of  each  set  of  matching 
bytes.  The  contents  of  the  searched  area  are  not  altered. 

The  range  parameter  specifies  the  starting  and  ending  address  or  the  starting  address  and 
length  in  bytes  of  the  area  to  be  searched.  If  a  segment  is  not  included  in  range,  SYMDEB 
uses  DS.  If  a  segment  is  specified  only  for  the  starting  address,  SYMDEB  uses  the  same  seg¬ 
ment  for  the  ending  address.  If  a  starting  address  and  length  in  bytes  are  specified,  the 
starting  address  plus  the  length  less  1  cannot  exceed  FFFFH. 

The  list  parameter  is  one  or  more  hexadecimal  byte  values  and/or  strings  separated  by 
spaces,  commas,  or  tab  characters.  Strings  must  be  enclosed  in  single  or  double  quotation 
marks,  and  case  is  significant  within  a  string. 

Examples 

To  search  for  the  string  Copyright  in  the  area  of  memory  from  DS:0000H  through 
DS:1FFFH,  type 

“S  0  1FFF  'Copyright'  <Enter> 

or 

“S  0  L2000  "Copyright"  <Enter> 

If  a  match  is  found,  SYMDEB  displays  the  address  of  each  occurrence: 

20A8:0910 

20A8:094F 

20A8:097C 
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To  search  for  the  byte  sequence  3BH  06H  in  the  area  of  memory  from  CSrOlOOH  through 
CS:12A0H,  type 

-S  CS:100  12A0  3B  06  <Enter> 

or 

-S  CSrIOO  L11A1  3B  06  <Enter> 
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SYMDEB:  S+ 

Enable  Source  Display  Mode 


Purpose 

Displays  source-code  lines,  rather  than  machine  instructions. 

Syntax 

s+ 

Description 

The  Enable  Source  Display  Mode  (S+)  command  affects  the  display  format  of  certain 
SYMDEB  commands:  Proceed  Through  Loop  or  Subroutine  (P),  Trace  Program  Execution 
(T),  and  Display  or  Modify  Registers  (R).  The  S+  command  causes  source  code,  rather  than 
disassembled  machine  instructions,  to  be  displayed  by  those  commands. 

The  S+  command  is  useful  only  if  the  program  being  debugged  was  created  with  a  high- 
level-language  compiler  capable  of  placing  line-number  information  into  the  relocatable 
object  modules  processed  by  the  Microsoft  Object  Linker  (LINK).  When  debugging 
Microsoft  Macro  Assembler  (MASM)  programs  or  programs  generated  by  language  com¬ 
pilers  that  do  not  pass  line-number  information  to  LINK,  the  S+  command  has  no  effect. 

Example 

To  enable  the  display  of  source-code  statements  during  debugging,  type 

-S+  <Enter> 
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SYMDEB:  S- 

Disable  Source  Display  Mode 


Purpose 

Displays  disassembled  machine  instructions,  rather  than  source-code  lines. 

Syntax 

s- 

Desctiption 

The  Disable  Source  Display  Mode  (S-)  command  affects  the  display  format  of  certain 
SYMDEB  commands:  Proceed  Through  Loop  or  Subroutine  (P),  Trace  Program  Execution 
(T),  and  Display  or  Modify  Registers  (R).  The  S-  command  causes  disassembled  machine 
instructions,  rather  than  source  code,  to  be  displayed  by  those  commands.  By  default, 
SYMDEB  displays  disassembled  machine  instructions  when  debugging  Microsoft  Macro 
Assembler  (MASM)  programs  or  programs  generated  by  language  compilers  that  do  not 
pass  line-number  information  to  the  Microsoft  Object  Linker  (LINK). 

Example 

To  disable  the  display  of  source-code  statements  during  debugging,  type 

-S-  <Enter> 
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SYMDEB:  S& 

Enable  Source  and  Machine  Code  Display  Mode 


Purpose 

Displays  both  source-code  lines  and  disassembled  machine  instructions. 

Syntax 

s& 

Description 

The  Enable  Source  and  Machine  Code  Display  Mode  (S&)  command  affects  the  display 
format  of  certain  SYMDEB  commands:  Proceed  Through  Loop  or  Subroutine  (P),  Trace 
Program  Execution  (T),  and  Display  or  Modify  Registers  (R).  The  S&  command  causes 
both  the  disassembled  machine  instructions  and  the  corresponding  source-code  lines  to 
be  displayed  by  those  commands. 

The  S&  command  is  useful  only  if  the  program  being  debugged  was  created  with  a  high- 
level-language  compiler  capable  of  placing  line-number  information  into  the  relocatable 
object  modules  processed  by  the  Microsoft  Object  Linker  (LINK).  When  debugging 
Microsoft  Macro  Assembler  (MASM)  programs  or  programs  generated  by  language  com¬ 
pilers  that  do  not  pass  line-number  information  to  LINK,  the  S&  command  has  no  effect. 

Example 

To  enable  the  display  of  both  source-code  statements  and  disassembled  machine-code 
statements  during  debugging,  type 

-S&  <Enter> 
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SYMDEB:  T 

Trace  Program  Execution 


Purpose 

Executes  one  or  more  machine  instructions  in  single-step  mode. 

Syntax 

T[=address]  [number] 
where: 

address  is  the  location  of  the  first  instruction  to  be  executed. 
number  is  the  number  of  machine  instructions  to  be  executed. 

Description 

The  Trace  Program  Execution  (T)  command  executes  one  or  more  machine  instructions, 
starting  at  the  specified  address.  If  source  display  mode  has  been  enabled  with  the  S+ 
command,  each  trace  operation  executes  the  machine  code  corresponding  to  one  source 
statement  and  displays  the  lines  from  the  source  code.  If  source  display  mode  has  been 
disabled  with  the  S-  command,  each  trace  operation  executes  an  individual  machine  in¬ 
struction  and  displays  the  contents  of  the  CPU  registers  and  flags  after  execution. 

Warning:  The  T  command  should  not  be  used  to  execute  any  instruction  that  changes  the 
contents  of  the  Intel  8259  interrupt  mask  (ports  20H  and  21H  on  the  IBM  PC  and  compat¬ 
ibles).  Use  the  Go  (G)  command  instead. 

The  address  parameter  points  to  the  first  instruction  to  be  executed.  If  address  does  not 
include  a  segment,  SYMDEB  uses  the  target  program’s  CS  register;  if  address  is  omitted 
entirely,  execution  is  begun  at  the  current  address  specified  by  the  target  program’s  CS:IP 
registers.  The  address  parameter  must  be  preceded  by  an  equal  sign  (=)  to  distinguish  it 
from  number. 

The  number  parameter  specifies  the  hexadecimal  number  of  source-code  statements 
or  machine  instructions  to  be  executed  before  the  SYMDEB  prompt  is  displayed  again 
(default  =  1).  If  source  display  mode  is  enabled,  the  number  parameter  is  required.  Execu¬ 
tion  of  a  sequence  of  instructions  using  the  T  command  can  be  interrupted  at  any  time  by 
pressing  Ctrl-C  or  Ctrl-Break  and  can  be  paused  by  pressing  Ctrl-S  (pressing  any  key 
resumes  the  trace). 

Examples 

To  execute  one  instruction  at  location  CS:1A00H  and  then  return  control  to  SYMDEB, 
displaying  the  contents  of  the  CPU  registers  and  flags,  type 

-T  =1A00  <Enter> 
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Consecutive  instructions  can  then  be  executed  by  entering  repeated  T  commands  with  no 
parameters. 

If  source  display  mode  has  been  enabled  with  a  previous  S+  command,  to  begin  execution 
at  the  label  main  and  continue  through  the  machine  code  corresponding  to  four  source- 
code  statements,  type 

-T  =_main  4  <Enter> 
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SYMDEB:  U 

Disassemble  (Unassemble)  Program 


Purpose 

Disassembles  machine  instructions  into  assembly-language  mnemonics. 

Syntax 

U  [range] 
where: 

range  specifies  the  starting  and  ending  addresses  or  the  starting  address  and  the 
number  of  instructions  of  the  machine  code  to  be  disassembled. 

Description 

The  Disassemble  (Unassemble)  Program  (U)  command  translates  machine  instructions 
into  their  assembly-language  mnemonics. 

The  range  parameter  specifies  the  starting  and  ending  addresses  or  the  starting  address 
and  number  of  machine  instructions  to  be  disassembled.  If  range  does  not  include  an 
explicit  segment,  SYMDEB  uses  CS.  Note  that  the  resulting  disassembly  will  be  incorrect  if 
the  starting  address  does  not  fall  on  an  8086  instruction  boundary. 

If  range  does  not  include  the  number  of  machine  instructions  to  be  executed  or  an  ending 
address,  eight  instructions  are  disassembled.  If  range  is  omitted  completely,  eight  instruc¬ 
tions  are  disassembled  starting  at  the  address  following  the  last  instruction  disassembled 
by  the  previous  U  command,  if  a  U  command  has  been  used;  if  no  U  command  has  been 
used,  eight  instructions  are  disassembled  starting  at  the  address  specified  by  the  current 
value  of  the  target  program’s  CS:IP  registers. 

The  display  format  for  the  U  command  depends  on  the  current  source  display  mode  set¬ 
ting  and  on  whether  the  program  was  developed  with  a  compatible  high-level-language 
compiler.  If  the  source  display  mode  setting  is  S-  or  the  program  was  developed  with  the 
Microsoft  Macro  Assembler  (MASM)  or  a  noncompatible  high-level-language  compiler,  the 
display  contains  only  the  address  and  the  disassembled  equivalent  of  each  instruction 
within  range.  (For  8-bit  immediate  operands,  SYMDEB  also  displays  the  ASCII  equivalent 
as  a  comment  following  a  semicolon.)  If  the  setting  is  S+  or  S&  and  a  compatible  symbol 
file  containing  line-number  information  was  loaded  with  the  program  being  debugged, 
the  display  contains  both  the  source-code  lines  and  their  corresponding  disassembled 
machine  instructions. 

Note:  The  80286  instructions  that  are  considered  privileged  when  the  microprocessor  is 
running  in  protected  mode  are  not  supported  by  SYMDEB’s  disassembler. 
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To  disassemble  four  machine  instructions  starting  at  CS:0100H,  type 

-U  100  L4  <Enter> 


This  produces  the  following  display: 


44DC:0100 

EC 

IN 

AL,DX 

44DC:0101 

B80200 

MOV 

AX, 0002 

44DC:0104 

E86102 

CALL 

0368 

44DC:0107 

57 

PUSH 

DI 

Successive  eight-instruction  fragments  of  machine  code  can  be  disassembled  by  entering 
additional  U  commands  without  parameters. 

When  a  program  is  being  debugged  with  a  symbol  file  that  contains  line-number  informa¬ 
tion  and  source  display  mode  has  been  enabled,  disassembled  machine  code  is  accom¬ 
panied  by  the  corresponding  source  code: 


43: 

if  (argc  !=  2) 

28A5:0031 

837E0402 

CMP 

Word  Ptr 

[BP+04],+02 

28A5:0035 

7503 

JNZ 

_jnain+2A 

(003A) 

28A5:0037 

E91400 

JMP 

_main+3E 

(004E) 

44: 

{ 

fprintf  (stderr,  ”\nciump 

:  wrong  number  of  parameters \n" 

28A5:003A 

B83600 

MOV 

AX, 0036 

28A5:003D 

50 

PUSH 

AX 

28A5:003E 

B8F600 

MOV 

AX,00F6 

28A5:0041 

50 

PUSH 

AX 

28A5:0042 

E8AC04 

CALL 

_f  print f 

28A5:0045 

83C404 

ADD 

SP,+04 

45: 

return  (1 ) ; 

28A5:0048 

B80100 

MOV 

AX, 0001 

28A5:004B 

E9AA00 

JMP 

_main+E8 

(00F8) 
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View  Source  Code 

Purpose 

Displays  lines  from  the  source-code  file  for  the  program  being  debugged. 

Syntax 

V  addressUength] 
or 

V  [  .sourcefile:  linenumber] 
where: 

address  is  the  location  of  an  executable  instruction  in  the  target  program. 

length  is  an  ending  address  or  the  number  of  source-code  lines. 

.sourcefile  is  the  base  name  of  the  source  file  of  the  program  being  debugged,  pre¬ 

ceded  by  a  period  (.). 

linenumber  is  the  first  literal  line  number  of  .sourcefile  to  be  displayed. 

Description 

The  View  Source  Code  (V)  command  displays  lines  of  source  code  for  the  program  being 
debugged,  beginning  at  the  location  specified  by  address.  If  address  does  not  include  a 
segment,  SYMDEB  uses  the  target  program’s  CS  register. 

The  optional  length  parameter  can  be  an  ending  address  or  an  L  followed  by  a  hexadeci¬ 
mal  number  of  source-code  lines.  If  length  is  not  specified,  eight  lines  of  source  code  are 
displayed. 

If  the  .sourcefile  parameter  is  specified,  followed  by  a  colon  character  (:)  and  a  line  num¬ 
ber,  eight  lines  of  source  code  are  displayed,  starting  at  linenumber.  If  the  V  command  is 
entered  without  parameters  after  the  .sourcefiledinenumber  parameter  has  been  speci¬ 
fied,  eight  lines  are  displayed  from  the  current  source  file,  beginning  with  the  line  after  the 
last  line  displayed  with  the  V  command.  The  .sourcefile  parameter  must  be  the  name  of  a 
high-level-language  source  file  in  the  current  directory.  Pathnames  and  extensions  are  not 
supported.  The  length  option  cannot  be  used  with  the  .sourcefile  parameter. 

Warning:  Specifying  a  file  that  does  not  exist  in  the  current  directory  may  cause  the  sys¬ 
tem  to  crash. 

The  V  command  can  be  used  only  with  programs  created  by  a  high-level-language  com¬ 
piler  that  is  capable  of  placing  line-number  information  into  the  relocatable  object  modules 
processed  by  the  Microsoft  Object  Linker  (LINK).  The  current  source  display  mode  setting 
6-,  S+,  or  S&)  has  no  effect  on  the  V  command. 
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Assume  that  the  program  DUMREXE  is  being  debugged  with  the  aid  of  the  symbol  file 
DUMRSYM  and  that  the  source  file  DUMRC  is  available  in  the  current  directory.  To  display 
eight  lines  of  source  code  beginning  at  the  label  type 

-V  _main  <Enter> 

This  produces  the  following  output: 

32:  int  argc; 

33:  char  *argv[]; 

34: 

35:  {  FILE  *dfile; 

36:  int  status  =  0; 

37:  int  file_rec  =  0; 

38:  long  file_ptr  =  OL; 

39:  char  f ilejDuf [REC^SIZE] ; 

To  view  eight  lines  of  source  code  from  the  file  DUMRC,  beginning  with  line  20,  type 

-V  .DUMP: 20  <Enter> 

Message 

Source  file  tot  filename  (cr  for  none)? 

The  current  directory  does  not  contain  the  source  file  specified  with  the  sourcefile 
parameter.  Enter  the  correct  filename  or  press  Enter  to  indicate  no  source  file. 


/*  control  block  for  input  file  */ 

/*  status  returned  from  file  read  */ 

/*  file  record  number  being  dumped  */ 
/*  file  byte  offset  for  current  rec  */ 
/*  data  block  from  file  */ 
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SYMDEB:  W 

Write  File  or  Sectors 


Purpose 

Writes  a  file  or  individual  sectors  to  disk. 

Syntax 

W  [address] 
or 

W  address  drive  start  number 
where: 

address  is  the  first  location  in  memory  of  the  data  to  be  written. 

drive  is  the  number  of  the  destination  disk  drive  (0  =  drive  A,  1  =  drive  B,  2  =  drive 

C,  3  =  drive  D). 

start  is  the  number  of  the  first  logical  sjector  to  be  written  (0  -  FFFFH). 

number  is  the  number  of  consecutive  sectors  to  be  written  (0  -  FFFFH). 

Description 

The  Write  File  or  Sectors  (W)  command  transfers  a  file  or  individual  sectors  from  memory 
to  disk. 

When  the  W  command  is  entered  without  parameters  or  with  an  address  alone,  the  num¬ 
ber  of  bytes  specified  by  the  contents  of  registers  BX:CX  are  written  from  memory  to  the 
file  named  by  the  most  recent  Name  File  or  Command-Tail  Parameters  (N)  command  or  to 
the  first  file  specified  in  the  SYMDEB  command  line  if  the  N  command  has  not  been  used. 

Note:  If  a  Go  (G),  Proceed  Through  Loop  or  Subroutine  (P),  or  Trace  Program  Execution 
(T)  command  was  previously  used  or  the  contents  of  the  BX  or  CX  registers  were  changed, 
BX:CX  must  be  restored  before  the  W  command  is  used. 

When  address  is  not  included  in  the  command  line,  SYMDEB  uses  the  target  program’s 
CS:0100H.  Files  with  a  .EXE  or  .HEX  extension  cannot  be  written  with  the  W  command. 

The  W  command  can  also  be  used  to  bypass  the  MS-DOS  file  system  and  obtain  direct 
access  to  logical  sectors  on  the  disk.  To  use  the  W  command  in  this  way,  the  memory 
address  {address),  disk  unit  number  {driv^,  starting  logical  sector  number  {start),  and 
number  of  sectors  to  be  written  {number)  must  all  be  provided  in  the  command  line  in 
hexadecimal  format. 

Warning:  Extreme  caution  should  be  used  with  the  W  command.  The  disk’s  file  structure 
can  easily  be  damaged  if  the  command  is  entered  incorrectly.  The  W  command  should  not 
be  used  to  write  logical  sectors  to  network  drives. 
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Assume  that  the  interactive  Assemble  Machine  Instructions  (A)  command  was  used  to 
create  a  program  in  SYMDEB’s  memory  buffer  that  is  32  (20H)  bytes  long,  beginning  at 
offset  lOOH.  This  program  can  be  written  into  the  file  QUICK.COM  by  sequential  use  of 
the  Name  File  or  Command-Tail  Parameters  (N),  Display  or  Modify  Registers  (R),  and  Write 
File  or  Sectors  (W)  commands.  First,  use  the  N  command  to  specify  the  name  of  the  file  to 
be  written: 

-N  QUICK.COM  <Enter> 

Next,  use  the  R  command  to  set  registers  BX  and  CX  to  the  length  to  be  written.  Register 
BX  contains  the  upper  half  or  most  significant  part  of  the  length;  register  CX  contains  the 
lower  half  or  least  significant  part.  Type 

^  CX  <Enter> 

SYMDEB  displays  the  current  contents  of  register  CX  and  issues  a  colon  character  (:) 
prompt .  Enter  the  length  after  the  prompt: 

:20  <Enter> 

To  use  the  R  command  again  to  set  the  BX  register  to  zero,  type 

BX  <Enter> 

Then  type 

:0  <Enter> 

To  create  the  disk  file  QUICK.COM  and  write  the  program  into  it,  type 

-W  <Enter> 

SYMDEB  responds: 

Writing  0020  bytes 

Messages 

EXE  andHEXnies  cannot  be  written 

Files  with  a  .EXE  or  .HEX  extension  cannot  be  written  to  disk  with  the  W  command. 

Writing  »itn»  bytes 

After  a  successful  write  operation,  SYMDEB  displays  in  hexadecimal  format  the  number  of 
bytes  written  to  disk. 
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SYMDEB:  X 

Examine  Symbol  Map 


Purpose 

Displays  names  and  addresses  in  the  symbol  maps. 

Syntax 

x[*] 

or 

X?  [mapi\  [segmenP]  [symbol] 
where: 

map\  is  the  name  of  a  symbol  file,  without  the  .SYM  extension,  followed  by  an 
exclamation  point  (!). 

segment:  is  the  name  of  a  segment  within  the  currently  open  or  specified  map^  followed 
by  a  colon  character  (:). 

symbol  is  a  symbol  name  within  the  specified  segment 

Description 

The  Examine  Symbol  Map  (X)  command  displays  the  addresses  and  names  of  symbols  in 
the  currently  open  symbol  maps,  (SYMDEB  maintains  a  symbol  map  for  each  symbol  file 
specified  in  the  SYMDEB  command  line.) 

If  the  X  command  is  followed  by  the  asterisk  wildcard  character  (*),  the  map  names, 
segment  names,  and  segment  addresses  for  all  currently  loaded  symbol  maps  are  dis¬ 
played.  If  X  is  entered  alone,  the  information  is  displayed  only  for  the  active  symbol  map. 

Information  from  the  symbol  maps  can  be  displayed  selectively  by  following  the  X?  com¬ 
mand  with  the  map\,  segment:,  and  symbol  parameters.  The  three  parameters  may  be 
used  individually  or  in  combination,  but  at  least  one  parameter  must  be  specified. 

The  map\  parameter  must  be  terminated  by  an  exclamation  point  and  consists  of  the 
name,  without  the  extension,  of  a  previously  loaded  symbol  file.  If  map\  is  omitted, 
SYMDEB  uses  the  currently  open  symbol  map.  If  more  than  one  .SYM  file  is  specified 
in  the  command  line,  the  one  with  the  same  name  as  the  program  being  debugged  is 
opened  first. 

The  segment:  parameter  must  be  terminated  with  a  colon;  it  is  the  name  of  a  segment 
declared  within  the  specified  or  currently  open  symbol  map. 

The  symbol  parameter  is  the  name  of  a  label,  variable,  or  other  object  within  the  specified 
segment 

Any  or  all  parameters  can  consist  of  or  include  the  asterisk  wildcard  character.  For  exam¬ 
ple,  X?*  displays  everything  in  the  current  map. 
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Assume  that  the  program  DUMP.EXE  is  being  debugged  with  the  symbol  file  DUMRSYM. 
If  the  following  is  typed 

-X  <Enter> 

SYMDEB  displays: 

[456E  DUMP] 

[456E  _TEXT] 

4743  DGROUP 

This  indicates  that  the  program  contains  one  executable  code  segment  (named  __TEXT), 
which  is  loaded  at  segment  456EH,  and  one  NEAR  DATA  group  and  segment  (named 
DGROUP),  which  is  loaded  at  segment  4743H. 

To  display  the  addresses  of  all  procedures  in  the  same  example  program  whose  names 
begin  with  the  character/  type 

-X?  _TEXT:_F*  <Enter> 

This  produces  the  following  listing: 

_TEXT;  (456E) 

0428  _fclose  04CB  _fopen  04F1  _fprintf 

0528  _fread  OACB  .fflush  0BC2  _free 

1 9AD  .flushall 

Note:  Unlike  the  Microsoft  C  Compiler,  SYMDEB  is  not  case  sensitive. 
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SYMDEBrXO 

open  Symbol  Map 


Purpose 

Selects  the  active  symbol  map  and/or  segment. 

Syntax 

XO  {mapi\  [segment] 
where: 

map\  is  the  name  of  a  symbol  file,  without  the  .SYM  extension,  followed  by  an 
exclamation  point  (!). 

segment  is  the  name  of  the  segment  that  will  become  the  active  segment  in  the  current 
symbol  map. 

Description 

The  Open  Symbol  Map  (XO)  command  selects  the  active  symbol  map  and/or  the  active 
segment  within  the  current  symbol  map  to  be  used  during  debugging. 

The  optional  map\  parameter  must  be  terminated  by  an  exclamation  point  and  must  be 
the  name,  without  the  extension,  of  a  symbol  file  specified  in  the  original  SYMDEB  com¬ 
mand  line.  If  map\  is  omitted,  no  changes  are  made  to  the  active  symbol  map. 

The  optional  segment  parameter  must  be  the  name  of  a  segment  within  the  current  or 
specified  symbol  map.  All  segments  in  the  active  symbol  map  are  accessible;  the  active 
segment  is  searched  first  for  symbols  specified  in  other  SYMDEB  commands.  If  segment  is 
omitted  and  a  new  active  symbol  map  is  specified,  the  segment  with  the  smallest  address 
in  the  new  active  symbol  map  will  become  the  active  segment. 

Examples 

Assume  that  the  program  SHELL.EXE  has  been  loaded  with  the  two  symbol  files 
SHELL.SYM  and  VIDEO.SYM.  To  use  the  information  loaded  from  VIDEO.SYM  as  the 
active  symbol  map  for  debugging,  type 

_X0  VIDEO!  <Enter> 

Subsequent  entry  of  the  command 

_X0  _TEXT  <Enter> 

causes  the  segment  _TEXT  within  the  symbol  map  VIDEO  to  be  searched  first  for  symbol 
names. 

Message 

Symbol  not  found 

The  specified  symbol  map  or  segment  does  not  exist. 


1140  The  MS-DOS  Encyclopedia 


SYMDEB:  2 


SYMDEB:  Z 

Set  Symbol  Value 


Purpose 

Assigns  a  value  to  a  symbol. 

Syntax 

Z  [map\\  symbol  value 
where: 

map\  is  the  name  of  a  symbol  file,  without  the  .SYM  extension,  followed  by  an  ex¬ 
clamation  point  (!). 

symbol  is  an  existing  symbol  name  in  the  active  symbol  map  or  in  the  symbol  map 
specified  by  map\. 

value  is  the  new  address  of  symbol  (0  ~  FFFFH). 

Description 

The  Set  Symbol  Value  (Z)  command  allows  the  address  associated  with  a  name  in  one  of 
the  loaded  symbol  maps  to  be  overridden  by  a  new  value. 

Note  that  altering  the  address  of  a  symbol  at  debugging  time  will  not  affect  other  addresses 
or  values  that  were  derived  from  the  value  of  the  same  symbol  at  compilation  or  assembly 
time. 

The  optional  map\  parameter  must  be  terminated  by  an  exclamation  point  and  must  be 
the  name,  without  the  extension,  of  a  symbol  file  specified  in  the  original  SYMDEB  com¬ 
mand  line.  If  map\  is  omitted,  SYMDEB  uses  the  active  symbol  map. 

The  symbol  parameter  specifies  the  name  of  a  label,  variable,  or  other  object  in  map\  or 
the  active  symbol  map. 

The  value  parameter  specifies  a  new  address  to  be  associated  with  symbol 

To  debug  programs  created  with  older  versions  of  FORTRAN  and  Pascal  (Microsoft  ver¬ 
sions  earlier  than  3.3  or  IBM  versions  earlier  than  2.0),  the  user  must  start  SYMDEB,  locate 
the  first  procedure  of  the  program  being  debugged,  and  then  use  the  Z  command  to  set 
the  address  of  DGROUP  to  the  current  value  of  the  DS  register.  (Later  versions  of 
FORTRAN  and  Pascal  do  this  by  default.) 
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To  change  the  segment  address  for  the  symbol  DGROUP  to  5000H,  type 

-Z  DGROUP  5000  <Enter> 

The  actual  data  associated  with  the  label  DGROUP  must  be  moved  to  the  new  address 
before  debugging  can  continue. 

To  change  the  segment  address  for  the  symbol  CODE  in  the  inactive  symbol  map  COUNT 
to  OFOOH,  type 

-Z  COUNT!  CODE  FOO  <Enter> 
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SYMDEB:  < 

Redirect  SYMDEB  Input 


Purpose 

Redirects  input  to  SYMDEB. 

Syntax 

<  device 
where: 

device  is  the  name  of  any  MS-DOS  device  or  file. 

Description 

The  Redirect  SYMDEB  Input  (<)  command  causes  SYMDEB  to  read  its  commands  from 
the  specified  text  file  or  character  device,  rather  than  from  the  keyboard  (CON). 

The  device  parameter  specifies  the  name  of  any  MS-DOS  device  or  file  from  which  com¬ 
mands  will  be  read.  If  the  device  parameter  is  a  filename,  the  file  must  be  an  ASCII  text 
file  and  each  command  in  the  file  must  be  on  a  separate  line. 

If  input  will  be  taken  from  a  terminal  attached  to  one  of  the  serial  communications  ports 
(AUX,  COMl,  or  COM2),  the  port  must  be  properly  configured  with  the  MODE  command 
before  the  SYMDEB  session  is  started. 

When  SYMDEB  commands  are  redirected  from  a  file,  the  last  entry  in  the  file  must  be 
either  the  <  CON  command,  which  restores  the  keyboard  as  the  input  device,  or  the  Quit 
(Q)  command.  Otherwise,  SYMDEB  will  lock  and  the  system  will  have  to  be  restarted. 

Examples 

Assume  that  the  text  file  FILL.TXT  contains  the  following  SYMDEB  commands: 

F  CS:0100  L100  00 
D  CS:0100  L100 
R 
Q 

To  process  FILL.TXT  during  a  SYMDEB  session  (which  in  turn  exits  SYMDEB  with  the 
Quit  [Q]  command),  type 

-<  FILL.TXT  <Enter> 
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Assume  that  the  text  file  SEARCH.TXT  contains  the  following  SYMDEB  commands: 

S  BUFFER  L2000  "error” 

<  CON 

To  process  SEARCH.TXT  during  a  SYMDEB  session  and  return  control  to  the  console,  type 

-  <  SEARCH . TXT  <Enter> 
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Redirect  SYMDEB  Output 


Purpose 

Redirects  SYMDEB’s  output  to  a  device  or  file. 

Syntax 

>  device 
where: 

device  is  the  name  of  any  MS-DOS  device  or  file. 

Description 

The  Redirect  SYMDEB  Output  (>)  command  causes  SYMDEB  to  send  all  its  messages  to 
the  specified  device  or  file,  rather  than  to  the  video  display  (CON).  This  is  useful  for  creat¬ 
ing  a  record  of  a  debugging  session  that  can  be  viewed  later  with  an  editor  or  listed  on  a 
printer. 

After  SYMDEB  output  is  redirected,  commands  typed  on  the  keyboard  are  not  echoed  to 
the  video  display.  Therefore,  the  user  must  know  in  advance  which  commands  to  use  and 
which  parameters  to  supply. 

The  device  parameter  specifies  the  name  of  an  MS-DOS  device  or  file  to  receive 
SYMDEB’s  output.  If  output  will  be  redirected  to  one  of  the  serial  communications  ports 
(AUX,  COMl,  or  COM2),  the  port  must  be  properly  configured  with  the  MODE  command 
before  the  SYMDEB  session  is  started. 

Output  can  be  restored  to  the  video  display  by  entering  the  >  CON  command  or  by  ter¬ 
minating  SYMDEB  with  the  Quit  (Q)  command. 

Examples 

To  cause  SYMDEB  to  send  all  prompts  and  messages  to  the  file  SESSION.TXT,  type 

->  SESSION.TXT  <Enter> 

After  this  command,  new  commands  are  still  accepted  by  SYMDEB,  but  the  keypresses 
are  not  echoed  to  the  screen  until  the  command 

->  CON  <Enter> 

is  entered  or  SYMDEB  is  terminated  with  the  Quit  (Q)  command. 

To  cause  SYMDEB  to  send  all  its  prompts  and  messages  to  the  standard  printing  device, 
PRN,  type 

->  PRN  <Enter> 
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SYMDEB:  = 

Redirect  SYMDEB  Input  and  Output 


Purpose 

Redirects  both  input  and  output  for  SYMDEB. 

Syntax 

=  device 
where: 

device  is  the  name  of  any  MS-DOS  device. 

Description 

The  Redirect  SYMDEB  Input  and  Output  (=)  command  causes  SYMDEB  to  read  its 
commands  from  and  send  its  output  to  the  specified  device,  rather  than  reading  from  the 
keyboard  and  sending  output  to  the  video  display  (CON).  This  command  is  especially  use¬ 
ful  for  debugging  programs  that  run  in  graphics  mode;  the  SYMDEB  commands  can  be  en¬ 
tered  on  a  terminal  attached  to  the  computer’s  serial  port  while  the  graphics  program  has 
the  full  use  of  the  system’s  video  display. 

The  device  parameter  specifies  the  name  of  any  MS-DOS  device.  If  input  and  output  will 
be  redirected  to  one  of  the  serial  communications  ports  (AUX,  COMl,  or  COM2),  the  port 
must  be  properly  configured  with  the  MODE  command  before  the  SYMDEB  session  is 
started. 

Input  and  output  can  be  restored  to  the  standard  settings  with  the  =  CON  command. 

Example 

To  redirect  SYMDEB’s  input  and  output  to  the  first  serial  communications  port  (COMl), 
type 

-=  COMl  <Enter> 
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SYMDEB:  { 

Redirect  Target  Program  Input 


Purpose 

Redirects  input  to  the  program  being  debugged. 

Syntax 

{ device 
where: 

device  is  the  name  of  any  MS-DOS  device  or  file. 

Description 

The  Redirect  Target  Program  Input  ({)  command  causes  read  operations  by  the  program 
being  debugged  to  be  taken  from  the  specified  file  or  device  when  the  program  is  exe¬ 
cuted,  rather  than  from  the  keyboard  (CON). 

The  device  parameter  specifies  the  name  of  an  MS-DOS  device  or  file  from  which  the 
target  program  will  read.  If  the  device  parameter  is  a  filename,  the  file  must  be  an  ASCII 
text  file  and  each  command  in  the  file  must  be  on  a  separate  line. 

If  input  will  be  taken  from  a  terminal  attached  to  one  of  the  serial  communications  ports 
(AUX,  COMl,  or  COM2),  the  port  must  be  properly  configured  with  the  MODE  command 
before  the  SYMDEB  session  is  started. 

Example 

To  cause  input  for  the  program  being  debugged  to  be  taken  from  the  file  TEST.TXT,  type 

-{  TEST.TXT  <Enter> 
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SYMDEB: } 

Redirect  Target  Program  Output 


Purpose 

Redirects  the  output  of  the  program  being  debugged. 

Syntax 

)  device 
where: 

device  is  the  name  of  any  MS-DOS  device  or  file. 

Description 

The  Redirect  Target  Program  Output  (!)  command  causes  write  operations  by  the  pro¬ 
gram  being  debugged  to  be  redirected  to  the  specified  device  or  file  when  the  program  is 
executed,  rather  than  to  the  video  display  (CON).  This  is  useful  for  capturing  the  output  of 
a  program  in  a  file  for  later  listing  on  a  printer. 

The  device  parameter  specifies  the  name  of  an  MS-DOS  device  or  file  to  receive  the  target 
program’s  output.  If  output  will  be  redirected  to  one  of  the  serial  communications  ports 
(AUX,  COMl,  or  COM2),  the  port  must  be  properly  configured  with  the  MODE  command 
before  the  SYMDEB  session  is  started. 

Example 

To  send  the  output  from  the  program  being  debugged  to  the  file  SESSION.TXT,  type 

-}  SESSION.TXT  <Enter> 
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SYMDEB: 

Redirect  Target  Program  Input  and  Output 


Purpose 

Redirects  both  input  and  output  for  the  program  being  debugged. 

Syntax 

~  device 
where: 

device  is  the  name  of  any  MS-DOS  device. 

Description 

The  Redirect  Target  Program  Input  and  Output  (r)  command  causes  all  read  and  write 
operations  by  the  program  being  debugged  to  be  redirected  to  the  specified  character 
device. 

The  device  parameter  specifies  the  name  of  an  MS-DOS  device  that  the  target  program 
will  read  from  and  write  to.  If  input  and  output  are  redirected  to  one  of  the  serial  commu¬ 
nications  ports  (AUX,  COMl,  or  COM2),  the  port  must  be  properly  configured  with  the 
MODE  command  before  the  SYMDEB  session  is  started. 

Example 

To  redirect  input  and  output  for  the  program  being  debugged  to  the  first  serial  communi¬ 
cations  port  (COMl),  type 

COMl  <Enter> 
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SYMDEB:  \ 

Swap  Screen 


Purpose 

Exchanges  the  SYMDEB  display  for  the  target  program’s  display. 

Syntax 

\ 

Description 

The  Swap  Screen  (\)  command  causes  the  SYMDEB  status  display  to  be  exchanged  for  the 
virtual  screen  used  by  the  program  being  debugged.  After  the  program’s  output  has  been 
inspected  on  the  virtual  screen,  the  SYMDEB  display  can  be  restored  by  pressing  any  key. 
This  command  is  useful  for  debugging  programs  that  perform  direct  screen  access  or  run 
in  graphics  mode. 

Note:  Any  information  on  the  display  when  SYMDEB  was  invoked  will  also  appear  on  the 
virtual  screen.  When  SYMDEB  is  terminated,  the  current  display  is  set  to  match  the  virtual 
screen. 

The  Swap  Screen  command  is  available  only  if  the  /S  switch  (or  the  /I  switch,  if  the  com¬ 
puter  is  IBM  compatible)  preceded  the  names  of  the  symbol  and  program  files  in  the  origi¬ 
nal  SYMDEB  command  line. 

Example 

To  exchange  the  SYMDEB  status  display  for  the  virtual  screen  of  the  program  being 
debugged,  type 

-\  <Enter> 

To  restore  the  SYMDEB  display,  press  any  key. 
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SYMDEB: . 

Display  Source  Line 


Purpose 

Displays  the  current  source-code  line. 

Syntax 

Description 

The  Display  Source  Line  (.)  command  displays  the  line  from  the  source-code  file  that 
corresponds  to  the  machine  instruction  currently  pointed  to  by  the  target  program’s  CS:IP 
registers. 

The .  command  is  independent  of  the  current  Source  Display  Mode  status  (S+,  S-,  or  S&). 
However,  if  the  program  being  debugged  was  not  created  with  a  high-level-language  com¬ 
piler  that  inserts  line  numbers  into  the  object  modules,  the .  command  has  no  effect. 

Example 

To  display  the  source-code  line  corresponding  to  the  next  instruction  to  be  executed,  type 

<Enter> 

This  produces  output  in  the  following  form: 

56:  printf(  ' \nDump  of  file:  %s  *,  argv[1]  ); 
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SYMDEB;  ? 

Help  or  Evaluate  Expression 


Purpose 

Displays  the  help  screen  or  the  value  of  an  expression. 

Syntax 

?  [expression] 
where: 

expression  is  any  valid  combination  of  symbols,  addresses,  numbers,  and  operators. 

Description 

When  ?  is  entered  alone,  a  help  screen  summarizing  all  valid  SYMDEB  commands,  opera¬ 
tors,  and  types  is  displayed. 

When  ?  is  followed  by  the  expression  parameter,  expression  is  evaluated  and  the  value  is 
displayed.  The  expression  parameter  can  include  any  valid  combination  of  symbols,  ad¬ 
dresses,  numbers,  and  operators. 

The  form  and  content  of  the  resulting  display  depends  on  the  type  of  expression  entered. 
If  expression  is  a  symbol  or  an  address  (optionally  including  operators),  the  value  is 
shown  first  as  a  FAR  address  pointer  in  the  form  segment:offset,  then  as  a  32-bit  hexadeci¬ 
mal  number  representing  the  value’s  physical  location  in  memory  (followed  by  its  decimal 
equivalent  in  parentheses),  and  finally  as  the  physical  location’s  ASCII  character  equiva¬ 
lents  displayed  as  a  string  enclosed  in  quotation  marks  (which  have  no  practical  value  if 
expression  is  an  address  or  symbol). 

If  expression  includes  numbers  (interpreted  as  signed  hexadecimal  values  unless  a  radix  is 
specified)  and  operators,  the  resulting  value  is  shown  first  as  a  l6-bit  hexadecimal  value, 
then  as  a  32-bit  hexadecimal  value  (followed  by  its  decimal  equivalent  in  parentheses), 
and  finally  as  the  value’s  ASCII  character  equivalents  displayed  as  a  string  enclosed  in 
quotation  marks. 

(The  ASCII  characters  within  the  string  are  displayed  as  dots  if  their  value  is  less  than  20H 
[32]  or  greater  than  7EH  [126].) 

Examples 

Assume  that  the  pointer  array  argv  in  the  program  DUMP.C  is  located  at  address 
4743:029CH.  The  command 

-  ?  _argv+4  <Enter> 

produces  the  following  display: 

4743:02A0h  000476D0  (292560) 
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To  display  the  result  of  an  exclusive  OR  operation  between  the  values  OFCH  and  14H,  type 

-?  FC  XOR  14  <Enter>. 

SYMDEB  displays 

OOESh  OOOOOOE8  (232) 
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SYMDEB: ! 

Escape  to  Shell 


Purpose 

Invokes  the  MS-DOS  command  processor. 

Syntax 

!  [command] 
where: 

command  is  the  name  of  any  MS-DOS  command,  program,  or  batch  file  and  its  re¬ 
quired  parameters. 

Description 

The  Escape  to  Shell  (!)  command  loads  a  copy  of  the  system’s  command  processor 
(COMMAND.COM),  optionally  passing  it  the  name  of  a  program  or  batch  file  to  be  exe¬ 
cuted.  This  allows  MS-DOS  functions  such  as  listing  or  copying  files  to  be  carried  out 
without  losing  the  context  of  the  debugging  session. 

If  the !  command  is  entered  alone,  an  additional  copy  of  COMMAND.COM  gains  control 
and  displays  the  system  prompt.  Control  can  be  returned  to  SYMDEB  by  leaving  the  new 
shell  with  the  EXIT  command. 

If  the  I  character  is  followed  by  a  command  parameter  that  specifies  any  valid  MS-DOS 
command,  program  name,  or  batch-file  name,  the  specified  command  is  executed  imme¬ 
diately  and  control  returns  directly  to  SYMDEB. 

The  SYMDEB  statement  connector  (;)  cannot  be  used  on  the  same  line  as  the  I  command; 
all  text  encountered  after  this  command  is  passed  to  COMMAND.COM  and  is  interpreted 
as  an  MS-DOS  command  line. 

Example 

To  list  the  files  in  the  current  directory,  type 

-!  DIR  /W  <Enter> 
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Messages 

COMMAND.COM  not  found! 

SYMDEB  could  not  find  COMMAND.COM  because  it  was  not  present  in  the  directory 
location  specified  in  the  environment  block’s  COMSPEC  variable. 

Not  enough  memory! 

Free  memory  in  the  transient  program  area  (TPA)  is  insufficient  to  execute  the  requested 
command  or  program.  This  is  a  common  occurrence  when  debugging  a  large  program 
with  symbol  files. 
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SYMDEB:  * 

Enter  Comment 


Purpose 

Allows  insertion  of  a  comment  that  will  be  ignored  by  SYMDEB’s  command  interpreter. 

Syntax 

*text 

where: 

text  is  any  ASCII  text  up  to  and  including  a  carriage  return. 

Description 

The  Enter  Comment  (♦)  command  causes  the  remainder  of  the  text  on  that  line  to  be 
ignored,  thereby  providing  a  means  of  commenting  a  SYMDEB  debugging  session. 
SYMDEB  echoes  any  text  following  the  asterisk  to  the  screen  or  redirected  output  device, 
providing  the  user  with  a  convenient  way  to  comment  program  output  redirected  to  a  file 
or  a  printer.  A  maximum  of  78  characters  can  be  included  on  each  comment  line.  Com¬ 
ment  lines  are  also  useful  for  documenting  lines  within  a  text  file  that  SYMDEB  will  use  as 
redirected  input  for  the  program  being  debugged. 

Example 

To  echo  the  reminder  Errors  in  program  output  start  here:  to  the  screen  or  redirected  out¬ 
put  device,  type 

”  *Errors  in  program  output  start  here :  <Enter> 

A  line  in  a  text  file  that  will  be  used  by  SYMDEB  for  redirected  input  to  the  program  being 
debugged  may  be  “commented  out”  by  inserting  an  asterisk  at  the  beginning  of  the  line. 
For  example: 

*EB  CS:1200  90 
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CodeView 

Window-Oriented  Debugger 


Purpose 

Allows  the  controlled  execution  of  an  assembly-language  program  or  high-level-language 
program  for  debugging  purposes.  Both  source  code  and  the  corresponding  unassembled 
machine  code  can  be  displayed  as  program  execution  is  traced.  In  addition,  watch  vari¬ 
ables,  CPU  registers  and  flags,  and  program  output  can  be  examined  in  separate  debug¬ 
ging  windows.  CodeView  is  supplied  with  the  Microsoft  Macro  Assembler  (MASM),  C 
Compiler,  Pascal  Compiler,  and  FORTRAN  Compiler.  This  documentation  describes 
CodeView  version  2.0. 

Syntax 

ON  [option^  exe^file  [ parameter 
where: 

exe^file  is  the  name  of  the  executable  file  containing  the  program  to  be  debugged 

(default  extension  =  .EXE). 

parameters  is  one  or  more  filenames  or  switches  required  by  the  program  being 

debugged. 

options  is  one  or  more  switches  from  the  following  list.  Switches  can  be  either 

uppercase  or  lowercase  and  can  be  preceded  by  a  dash  (-)  instead  of  a 
forward  slash  (/). 

/2  Allows  the  use  of  two  video  displays  for  debugging. 

/43  Enables  43-line  display  mode.  (An  IBM-compatible 

computer  with  an  enhanced  graphics  adapter  [EGA] 
and  an  enhanced  color  display  is  required  for  this 
option.) 

Forces  the  attached  monitor  to  use  two  shades  of  color 
when  displaying  information. 

Executes  the  specified  list  of  startup  commands  when 
CodeView  is  invoked.  If  the  list  of  startup  commands 
contains  any  spaces,  the  entire  list  must  be  enclosed  in 
double  quotation  marks  (").  Commands  in  the  list  must 
be  separated  by  a  semicolon  character  (;). 

Turns  off  nonmaskable  interrupt  trapping  and  Intel 
8259  interrupt  trapping.  (This  switch  prevents  system 
crashes  on  some  IBM-compatible  machines  that  do 
not  support  certain  IBM-specific  interrupt  trapping 
functions.) 


/B 

/Qcommands 

/D 


(more) 
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/E  Stores  the  symbolic  information  of  the  program  in 

expanded  memory. 

/F  Enables  the  screen-flipping  method  of  switching 

between  the  debugging  display  and  the  virtual  output 
display.  Screen  flipping  is  the  default  method  for 
IBM-compatible  computers  with  color/graphics 
adapters. 

/I  Enables  nonmaskable  interrupt  trapping  and  Intel 

8259  interrupt  trapping  on  computers  that  are  not 
IBM-compatible. 

/M  Disables  mouse  support  within  CodeView. 

/P  Enables  palette  register  restore  mode,  which  allows 

non-IBM  EGAs  to  restore  the  proper  colors  upon  return 
from  the  virtual  output  screen. 

/R  Enables  Intel  80386  debugging  registers. 

/S  Enables  the  screen-swapping  method  of  switching 

between  the  debugging  display  and  the  virtual  output 
display.  Screen  swapping  is  the  default  method  for 
IBM-compatible  computers  with  monochrome 
adapters. 

/T  Disables  window  mode.  This  switch  is  necessary  for 

some  non-IBM  computers  or  when  a  sequential  debug¬ 
ging  session  is  desired. 

/W  Enables  window  mode.  This  switch  allows  CodeView 

to  operate  in  multiple  windows  on  the  same  screen. 
(This  option  is  not  the  default  for  some  computers.) 

Description 

CodeView  is  a  window-oriented  menu-driven  debugger  that  allows  tracing  and  debugging 
of  high-level-language  programs  and  assembly-language  programs.  In  general,  any  valid  C, 
FORTRAN,  BASIC,  Pascal,  or  MASM  source  code  can  be  debugged  with  CodeView. 

To  prepare  a  program  for  debugging  under  CodeView,  the  program  must  be  compiled  and 
linked  so  that  the  resulting  executable  file  has  the  extension  .EXE  and  contains  line- 
number  information,  a  symbol  table,  and  executable  code.  (To  a  limited  extent,  text  files 
and  .COM  files  can  also  be  examined  under  CodeView.)  During  the  debugging  session, 
the  program  source  file  must  remain  in  the  current  directory  if  source-code  display  is 
desired. 

The  CodeView  screen  contains  four  windows  that  display  information  about  the  pro¬ 
gram  being  debugged:  the  display  window,  which  contains  program  source  code  and  (if 
requested)  the  unassembled  machine  code  corresponding  to  the  source  code;  the  dialog 
window,  where  line-oriented  commands  similar  (and  in  some  cases  identical)  to  SYMDEB 
can  be  entered  and  viewed  isee  PROGRAMMING  UTILITIES:  symdeb);  the  register  win¬ 
dow  (optional),  which  contains  the  current  status  of  the  microprocessor’s  registers  and 
flags;  and  the  watch  window  (optional),  which  contains  program  variables  or  memory 
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locations  to  be  examined  during  program  execution.  CodeView  also  provides  a  virtual 
output  screen  (stored  internally)  that  contains  all  display  output  generated  during  the 
CodeView  session. 

A  typical  CodeView  debugging  screen  looks  like  this: 


Watch  window 


Pull-down  menu 


Display 

window 


Next 
executable 
program 
line 


get_f i le 


mou  dx, OFFSET  nanebuf 
dosint  0Ah 
nou  siidx 

nou  bl,BVTE  PTR  tsiUl 
nog  BYTE  PTR  [si*bx*21,l 

nou  dliBAh 


Load  address  for  fil 
Get  file  nane  string 
Set  SI  to  start  of  f 
Put  the  number  of  by 
Put  0  at  end  to  nake 
(0  overrides  CR  fr 
Load  linefeed  characQ 


hicrosoft  (R)  CodeUieu  (R)  Uersion  2.00 
1(0  Copyright  Microsoft  Corp.  1986,  1987. 


All  rights  reserved. 


Register 

window 


Dialog  window 
The  CodeView  display. 


Scroll  bars 


Display  window  commands 

Commands  that  control  the  display  window  are  available  in  nine  pull-down  menus  whose 
names  appear  in  a  menu  bar  near  the  top  of  the  screen.  Commands  can  be  selected  with 
the  keyboard  or  the  mouse.  Commands  are  selected  with  the  keyboard  by  pressing  the  Alt 
key,  pressing  the  first  letter  in  the  menu  name,  and  then  pressing  the  first  letter  of  the  com¬ 
mand.  Commands  are  selected  with  the  mouse  by  pulling  down  the  menu  with  the  mouse 
pointer,  highlighting  the  command,  and  then  releasing  the  mouse  button.  Commands  with 
small  double  arrows  to  the  left  of  the  command  name  are  currently  active.  The  CodeView 
menus  and  commands  are  described  below. 

File  menu 

The  File  menu  includes  commands  that  manipulate  the  current  source  or  program  file.  To 
select  the  File  menu  with  the  keyboard,  press  Alt-F. 


Command  Action 


Open . . . 

DOS  Shell 
Exit 


Opens  the  specified  source  file,  include  file,  or  text  file  in  the  display 
window. 

Exits  to  the  shell  temporarily.  Type  exit  to  return  to  CodeView. 

Ends  the  current  CodeView  session. 
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View  menu 

The  View  menu  includes  commands  that  select  source  or  assembly  modes  and  commands 
that  select  the  debugging  screen  or  the  virtual  output  screen.  To  select  the  View  menu  with 
the  keyboard,  press  Alt-V. 


Command 

Action 

Source 

Mixed 

Assembly 

Registers 

Output 

Displays  only  the  high-level-language  or  assembly-language  source  code 
corresponding  to  the  program  being  debugged. 

Displays  both  the  unassembled  machine  code  and  the  source  code 
corresponding  to  the  program  being  debugged. 

Displays  only  the  unassembled  machine  code  corresponding  to  the 
program  being  debugged. 

Displays  or  removes  the  optional  register  window. 

Replaces  the  debugging  screen  with  the  virtual  output  screen.  Press  any 
key  to  return  to  the  debugging  screen. 

Search  menu 

The  Search  menu  includes  commands  that  search  through  text  files  for  text  strings  and 
through  executable  code  for  labels.  To  select  the  Search  menu  with  the  keyboard,  press 
Alt-S. 

Command 

Action 

Find... 

Next 

Previous 

Label... 

Searches  the  current  source  file  or  other  text  file  for  the  specified 
expression. 

Searches  forward  through  the  file  for  the  next  match  of  the  last 
expression  specified  with  the  Find . . .  command. 

Searches  backward  through  the  file  for  the  next  match  of  the  last 
expression  specified  with  the  Find . . .  command. 

Searches  the  executable  code  for  the  specified  procedure  name  or 
program  label. 

Run  menu 

The  Run  menu  includes  commands  that  run  the  program  being  debugged.  To  select  the 
Run  menu  with  the  keyboard,  press  Alt-R. 

Command 

Action 

Start 

Restart 

Execute 

Runs  the  program  at  full  speed  from  the  first  instruction. 

Reloads  the  program  and  moves  to  the  first  instruction. 

Runs  the  program  at  reduced  speed  from  the  current  instruction. 

Clear  Breakpoints  Clears  all  breakpoints. 
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Watch  menu 

The  Watch  menu  includes  commands  that  add  watch  statements  to  and  delete  watch  state¬ 
ments  from  the  watch  window.  Watch  statements  describe  expressions  or  areas  of  memory 
to  be  examined  during  program  execution.  To  select  the  Watch  menu  with  the  keyboard, 
press  Alt-W. 


Command  Action 


Add  Watch... 
Watchpoint... 

Tracepoint... 

Delete  Watch... 
Delete  All  Watch 


Adds  the  specified  watch-expression  statement  to  the  watch 
window. 

Adds  the  specified  watchpoint  statement  to  the  watch  window.  A 
watchpoint  is  a  conditional  breakpoint  that  is  taken  when  the 
expression  becomes  nonzero  (true). 

Adds  the  specified  tracepoint  statement  to  the  watch  window.  A 
tracepoint  is  a  conditional  breakpoint  that  is  taken  when  a  given 
expression  or  range  of  memory  changes. 

Deletes  the  specified  statement  from  the  watch  window. 

Deletes  all  statements  from  the  watch  window. 


Options  menu 

The  Options  menu  contains  commands  that  affect  the  general  behavior  of  CodeView.  To 
select  the  Options  menu  with  the  keyboard,  press  Alt-O. 


Command  Action 


Flip/Swap 


Bytes  Coded 


Case  Sense 


386 


When  on  (the  default),  enables  screen  swapping  or  screen  flipping 
(whichever  option  CodeView  was  started  with);  when  off,  disables 
swapping  or  flipping.  Either  method  can  be  used  to  display  the 
CodeView  virtual  output  screen. 

When  on  (the  default),  displays  the  instructions,  instruction  addresses, 
and  the  bytes  for  each  instruction;  when  off,  displays  only  the 
instructions. 

When  on,  causes  CodeView  to  assume  that  symbol  names  are  case  sensi¬ 
tive;  when  off,  causes  CodeView  to  assume  that  symbol  names  are  not 
case  sensitive.  This  option  is  on  by  default  for  C  programs  and  off  by 
default  for  FORTRAN,  BASIC,  and  assembly  programs. 

When  on,  allows  instructions  that  reference  32-bit  instructions  to  be  as¬ 
sembled  and  executed  and  the  register  window  to  display  32-bit  values. 
When  off,  does  not  allow  Intel  80386  instructions  and  registers  to  be 
supported. 


Language  menu 

The  Language  menu  contains  commands  that  select  the  language-dependent  expression 
evaluator  or  instruct  CodeView  to  select  it  for  you.  To  select  the  Language  menu  with  the 
keyboard,  press  Alt-L. 
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Command  Action 


Auto 

Basic 

C 

Fortran 


Forces  CodeView  to  select  the  expression  evaluator  of  the  source  file 
being  loaded,  based  on  the  extension  of  the  source  file. 

Uses  a  BASIC  expression  evaluator  to  determine  the  value  of  source-level 
expressions. 

Uses  a  C  expression  evaluator  to  determine  the  value  of  source-level 
expressions. 

Uses  a  FORTRAN  expression  evaluator  to  determine  the  value  of  source- 
level  expressions. 


Calls  menu 

The  Calls  menu  is  different  from  other  menus  in  that  its  contents  vary  depending  on  the 
status  of  the  program.  The  Calls  menu  lists  the  names  of  specific  routines  that  will  be  dis¬ 
played  on  the  screen  when  that  routine  name  is  selected.  Routine  names  in  the  Calls  menu 
can  be  selected  by  typing  the  number  displayed  immediately  to  the  left  of  a  routine  name. 
The  cursor  will  move  to  the  line  at  which  the  selected  routine  was  last  executing. 

The  current  value  of  each  parameter,  if  any,  is  shown  in  parentheses  following  the  name 
of  the  routine  in  the  Calls  menu.  The  menu  expands  to  accommodate  the  parameters  of 
the  widest  line.  Parameters  are  shown  in  the  current  radix  (default  =  decimal).  If  the 
program  contains  more  active  routines  than  will  fit  on  the  screen  or  if  the  routine  parame¬ 
ters  are  too  wide,  the  menu  expands  to  the  left  and  right. 

To  select  the  Calls  menu  with  the  keyboard,  press  Alt-C. 

Help  menu 

The  Help  menu  lists  the  major  topics  in  the  CodeView  “linked-list”  help  system.  For  help, 
pull  down  the  Help  menu  and  then  select  the  topic  of  interest.  To  select  the  Help  menu 
with  the  keyboard,  press  Alt-H. 


Command  Action 


Intro  to  Help 
Keyboard/Mouse 
Run  commands 
Display  cmds. 
Watch/Break 

Memory  Ops 
System  cmds. 
About  CodeView 


Displays  information  about  the  “linked-list”  help  system. 
Displays  information  about  keyboard  and  mouse  commands. 
Displays  information  about  Run  commands. 

Displays  information  about  Display  commands. 

Displays  information  about  setting,  listing,  and  deleting  watch- 
points  and  breakpoints. 

Displays  information  about  viewing  and  modifying  memory. 
Displays  information  about  system  and  environment  commands. 
Displays  information  about  the  current  CodeView  version,  time, 
and  date. 
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Key  commands 

CodeView  supports  a  variety  of  function  keys  and  key  combinations  that  modify  the  active 
window. 


Key  Action 


FI 

F2 

F3 

F4 

F5 

F6 

F7 

F8 

F9 

FIO 

Ctrl+G 

Ctrl+T 


Displays  the  introductory  help  screen. 

Displays  or  removes  the  register  window. 

Changes  the  display  in  the  display  window  to  source,  mixed,  or  assembly 
mode. 

Displays  the  virtual  output  screen  (press  any  key  to  return). 

Executes  to  the  next  breakpoint  or  to  the  end  of  the  program  if  no  break¬ 
point  is  encountered. 

Toggles  between  the  display  window  and  the  dialog  window. 

Sets  a  temporary  breakpoint  on  the  line  containing  the  cursor  and  exe¬ 
cutes  to  that  line  (or  the  next  breakpoint). 

Executes  a  trace  command,  stepping  through  program  calls  if  present. 

Sets  or  clears  a  breakpoint  on  the  line  containing  the  cursor. 

Executes  the  next  source  line  (in  source  mode)  or  the  next  instruction 
(in  assembly  mode),  stepping  over  program  calls  if  present. 

Increases  the  size  of  the  display  window  or  the  dialog  window,  whichever 
is  active. 

Decreases  the  size  of  the  display  window  or  the  dialog  window,  whichever 
is  active. 


Dialog  window  commands 

After  CodeView  and  the  specified  executable  file  are  loaded,  CodeView  displays  its  special 
prompt  character  (>)  at  the  bottom  of  the  dialog  window  and  awaits  a  dialog  command. 
CodeView  dialog  commands  consist  of  one,  two,  or  three  characters,  usually  followed  by 
one  or  more  parameters.  CodeView  treats  uppercase  and  lowercase  characters  the  same 
except  when  they  are  contained  in  strings  enclosed  within  single  or  double  quotation 
marks.  The  default  radix  for  dialog  command  parameters  is  10  (decimal).  Dialog  com¬ 
mands  are  executed  when  the  Enter  key  is  pressed. 

A  detailed  explanation  of  CodeView  dialog  commands  and  parameters  is  not  presented 
in  this  entry.  CodeView  dialog  commands  and  parameters  are  similar  to  SYMDEB  com¬ 
mands  and  parameters.  See  PROGRAMMING  UTILITIES:  symdeb.  Additional  information 
about  using  CodeView  dialog  commands  and  parameters  can  be  found  in  the  CodeView 
documentation  supplied  with  the  Microsoft  Macro  Assembler  (MASM),  C  Compiler,  Pascal 
Compiler,  and  FORTRAN  Compiler.  A  sample  debugging  session  using  CodeView  dialog 
commands  and  window  commands  is  documented  in  this  book.  See  PROGRAMMING  IN 
THE  MS-DOS  ENVIRONMENT:  Programming  Tools:  Debugging  in  the  MS-DOS 
Environment. 
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The  dialog  commands  available  with  CodeView  are  as  follows: 


Command 

Syntax 

Action 

1 

!  [command] 

Escape  to  shell. 

II 

II 

Pause  redirected  file  execution. 

# 

^number 

Set  display  window  tabs. 

♦ 

*  comment 

Echo  comment  to  output  device. 

Display  current  source  line. 

/ 

/[searchtext] 

Search  for  regular  expression. 

7 

1 

Display  8087  registers. 

Delay  redirected  file  execution. 

< 

<  device 

Redirect  dialog  window  input. 

= 

=  device 

Redirect  dialog  window  input  and  output. 

> 

[T]  >  [>]  device 

Redirect  dialog  window  output. 

? 

?  expression[Jormat\ 

Evaluate  expression. 

@ 

@ 

Redraw  screen. 

A 

A  [address 

Assemble  machine  instructions. 

BC 

BC  [♦]  [list] 

Clear  breakpoints. 

BD 

BD  [♦]  [list] 

Disable  breakpoints. 

BE 

BE  [♦]  [list] 

Enable  breakpoints. 

BL 

BL 

List  breakpoints. 

BP 

BP  [address  [passcounf] 

Set  breakpoints. 

["cmrfs"]] 

C 

C  range  address 

Compare  memory  areas. 

D 

D  [range] 

Display  (dump)  memory. 

DA 

DA  [range] 

Display  ASCII. 

DB 

DB  [range] 

Display  bytes. 

DD 

DD  [range] 

Display  doublewords. 

DI 

DI  [range] 

Display  integers. 

DL 

DL  [range] 

Display  long  reals. 

DS 

DS  [range] 

Display  short  reals. 

DT 

DT  [range] 

Display  10-byte  reals. 

DU 

DU  [range] 

Display  unsigned  integers. 

DW 

DW  [range] 

Display  words. 

E 

E  address  [list] 

Enter  data. 

EA 

EA  address  [list] 

Enter  ASCII  string. 

EB 

EB  address  [list] 

Enter  bytes. 

ED 

ED  address  [value] 

Enter  doublewords. 

El 

El  address  [list] 

Enter  integers. 

EL 

EL  address  [value] 

Enter  long  reals. 

ES 

ES  address  [value] 

Enter  short  reals. 

ET 

ET  address  [value] 

Enter  10-byte  reals. 

(more) 
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Command 

Syntax 

EU 

EU  address  [value] 

EW 

EW  address  [value] 

F 

F  range  list 

G 

G  [breakpoint] 

H 

H 

I 

I  port 

K 

K  [number] 

L 

L  [parameters] 

M 

M  range  address 

N 

N  [radix] 

O 

O  port  byte 

O 

O 

03 

031+ 1-] 

OB 

OB[+!-] 

OC 

OC[+l-] 

OF 

OF[+!-] 

P 

P  [count] 

Q 

Q 

R 

R  [register  [value]] 

RF 

RF  [flags] 

S 

S  range  list 

s 

S 

s+ 

S+ 

s- 

S- 

s& 

S& 

T 

T  [count] 

TP 

TP  [type]  range 

TP? 

TP?  expression[,  format] 

U 

U  [range] 

USE 

USE  [language] 

V 

V  [.[  filename.]linenumber] 

W 

W 

W 

W  [type]  range 

W? 

W?  expression[,  format] 

WP? 

WP?  expression[Jormat] 

X 

X[?[morfwfe!] 

[  routine  ]symbol  1  ♦] 

Y 

Y[*][list] 

\ 

\ 

Action 

Enter  unsigned  integers. 

Enter  words. 

Fill  memory. 

Go  execute  program. 

Display  help  screen. 

Input  from  port. 

Perform  stack  trace. 

Reload  program. 

Move  (copy)  data. 

Change  current  radix. 

Output  to  port. 

Display  all  options. 

Toggle  Intel  80386  option. 

Toggle  bytes  coded  option. 

Toggle  case-sense  option. 

Toggle  flip/swap  option. 

Step  through  program  (over  calls). 

Quit  debugger. 

Display  or  modify  registers. 

Display  or  modify  flags. 

Search  memory. 

Display  current  display  mode. 

Display  source  code. 

Display  assembly  language. 

Display  source  code  and  assembly 
language. 

Trace  program  execution  (through  calls). 
Set  memory-tracepoint  statement. 

Set  tracepoint-expression  statement. 
Disassemble  (unassemble)  program. 
Switch  expression  evaluators. 

View  source  code. 

List  watchpoints  and  tracepoints. 

Set  memory-watch  statement. 

Set  watch-expression  statement. 
Setwatchpoint. 

Examine  program  symbols. 

Delete  watch  statements. 

Display  virtual  output  screen. 
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Examples 

To  prepare  the  source  file  SHELL.C  for  debugging  with  CodeView,  first  compile  the  source 
file  with  the  switches  that  disable  optimization  and  cause  symbol-table  and  line-number 
information  to  be  written  to  the  relocatable  object  module: 

C>MSC  /Zi  /Od  SHELL;  <Enter> 

Next,  to  convert  the  object  module  to  an  executable  program  and  prepare  it  for  CodeView, 
type 

OlINK  /CO  SHELL;  <Enter>  . 

To  begin  debugging,  type 

C>cv  SHELL  <Enter> 

To  start  CodeView  in  43-line  mode  with  TEST.EXE  as  the  executable  file  and  INFO.DAT  as 
the  command-tail  parameter,  type 

C>cv  /43  TEST  INFO.DAT  <Enter> 

In  both  examples  the  source  file  corresponding  to  the  specified  executable  file  must  be  in 
the  current  directory  if  source-code  display  is  desired. 

Messages 

Argument  to  IMAG/DIMAG  must  be  simple  type 

An  invalid  parameter  to  an  IMAG  or  DIMAG  function,  such  as  an  array  with  no  subscripts, 
was  specified. 

Array  must  have  subscript 

An  array  without  any  subscripts  was  specified  in  an  expression,  such  as  IARRAY+2,  A 
correct  example  is  IARRAY[l]+2. 

Bad  address 

An  invalid  address  was  specified.  For  example,  an  address  containing  hexadecimal  char¬ 
acters  might  have  been  specified  when  the  radix  is  decimal. 

Bad  breakpoint  command 

An  invalid  breakpoint  number  was  specified  with  the  BC,  BD,  or  BE  dialog  command.  The 
breakpoint  number  must  be  in  the  range  0  through  19. 

Bad  flag 

An  invalid  flag  mnemonic  was  specified  with  the  RF  dialog  command. 

Bad  format  string 

An  invalid  format  specifier  was  used  following  an  expression.  Expressions  used  with  the 
?,  W?,  WP?,  and  TP?  dialog  commands  can  have  format  specifiers  set  off  from  the  expres¬ 
sion  by  a  comma.  The  valid  format  specifiers  are  c,  d,  e,  E,  f,  g,  G,  i,  o,  s,  u,  x,  and  X.  Some 
format  specifiers  can  be  preceded  by  the  prefix  h  (to  specify  a  2-byte  integer)  or  1  (to  spec¬ 
ify  a  4-byte  integer). 
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Bad  integer  or  real  constant 

An  invalid  numeric  constant  was  specified  in  an  expression. 

Bad  intrinsic  function 

An  invalid  intrinsic  function  name  was  specified  in  an  expression. 

Badly  formed  type 

The  type  information  in  the  symbol  table  of  the  file  being  debugged  is  incorrect.  This  is  a 
serious  problem.  Note  the  circumstances  of  the  failure  and  notify  Microsoft  Corporation. 

Bad  radix  (use  8, 10,  or  16) 

An  invalid  radix  was  specified  with  the  N  dialog  command.  Use  an  octal,  decimal,  or 
hexadecimal  radix. 

Bad  register 

An  invalid  register  name  was  specified  with  the  R  dialog  command.  Use  AX,  BX,  CX,  DX, 
SP,  BP,  SI,  DI,  DS,  ES,  SS,  CS,  or  IP.  If  your  machine  is  equipped  with  an  Intel  80386  micro¬ 
processor,  use  EAX,  EBX,  ECX,  EDX,  ESP,  EBP,  ESI,  EDI,  DS,  ES,  FS,  GS,  SS,  CS,  or  IP. 

Bad  subscript 

An  invalid  subscript  expression  was  specified  for  an  array,  such  as  lARRAY (33)  or 
I  ARRAY  ((33)X  The  correct  expression  for  this  example  (in  BASIC  or  FORTRAN)  is 
lARRAY  (33). 

Bad  type  cast 

Incompatible  types  of  operands  were  specified  in  an  expression. 

Badtype(use  one  of  ABDBLSTUW*) 

An  invalid  type  was  used  in  a  Display  (D,  DA,  DB,  DF,  DU,  DW,  DD,  DS,  DL,  or  DT)  dialog 
command.  The  valid  types  are  ASCII  (A),  byte  (B),  integer  (I),  unsigned  (U),  word  (W), 
doubleword  (D),  short  real  (S),  long  real  (L),  and  10-byte  real  (T). 

Breakpoint  #  or expected 

The  BC,  BD,  or  BE  dialog  command  was  entered  without  a  parameter. 

Cannot  cast  complex  constant  component  into  REAL 

An  incompatible  real  or  imaginary  component  was  specified  in  a  COMPLEX  constant. 
Both  real  and  imaginary  components  must  be  compatible  with  type  REAL. 

Cannot  cast  IMAG/DIMAG  argument  to  COMPLEX 

An  invalid  parameter  was  specified  with  an  IMAG  or  DIMAG  function.  IMAG  and  DIMAG 
parameters  must  be  simple  numeric  types. 

Cannot  use  struct  or  union  as  scalar 

A  struct  or  union  variable  was  used  as  a  scalar  value  in  a  C  expression.  Such  variables  must 
be  followed  by  a  file  specifier  or  preceded  by  the  address-of  (&)  operator. 

Can’t  find  fUename 

CodeView  could  not  find  the  executable  file  specified  in  the  command  line. 
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Character  constant  too  long 

A  character  constant  that  is  too  long  for  the  FORTRAN  expression  evaluator  was  specified. 
The  limit  is  126  bytes. 

Character  too  big  for  current  radix 

A  radix  that  is  larger  than  the  current  CodeView  radix  was  specified  in  a  constant.  Use  the 
N  dialog  command  to  change  the  radix. 

Constant  too  big 

An  unsigned  constant  number  larger  than  4,294,967,295  (FFFFFFFFH)  was  specified. 

CPU  not  an  80386 

The  386  option  was  selected  but  a  machine  without  an  Intel  80386  microprocessor  is 
being  used. 

Divide  by  zero 

An  expression  in  a  parameter  of  a  dialog  command  attempted  to  divide  by  zero. 

EMM  error 

CodeView  failed  to  use  the  Expanded  Memory  Manager  (EMM)  correctly.  This  is  a  serious 
problem.  Note  the  circumstances  of  the  failure  and  notify  Microsoft  Corporation. 

EMM  hardware  error 

The  Expanded  Memory  Manager  (EMM)  routines  reported  a  hardware  error.  Check  your 
expanded  memory  board  for  defects. 

EMM  memory  not  found 

The  /E  option  was  used  but  expanded  memory  has  not  been  installed.  Install  software 
that  accesses  the  memory  according  to  the  Lotus/Intel/Microsoft  Expanded  Memory 
Specification  (LIM  EMS). 

EMM  software  error 

The  Expanded  Memory  Manager  (EMM)  routines  reported  a  software  error.  Reinstall  the 
EMM  software. 

Expression  too  complex 

An  expression  given  as  a  dialog-command  parameter  is  too  complex. 

Extra  input  ignored 

Too  many  parameters  were  specified  with  a  command.  CodeView  evaluates  the  valid 
parameters  and  ignores  the  rest.  In  this  situation,  CodeView  often  does  not  evaluate  the 
parameters  as  intended. 

Flip/Swap  option  off  —  application  output  lost 

The  program  being  debugged  is  writing  to  the  screen,  but  the  output  cannot  be  displayed 
because  the  f  lip/swap  option  has  been  disabled. 

Floating  point  error 

This  is  a  serious  problem.  Note  the  circumstances  of  the  failure  and  notify  Microsoft 
Corporation. 
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Illegal  instruction 

This  message  usually  indicates  that  a  machine  instruction  attempted  to  divide  by  zero. 

Index  out  of  bound 

A  subscript  value  was  specified  that  is  outside  the  bounds  declared  for  the  array. 

Insufficient  EMM  memory 

Expanded  memory  is  insufficient  to  hold  the  program’s  symbol  table. 

Internal  debugger  error 

This  is  a  serious  problem.  Note  the  circumstances  of  the  failure  and  notify  Microsoft 
Corporation. 

Invalid  argument 

An  invalid  CodeView  expression  was  specified  as  a  parameter. 

Invalid  executable  file  format — please  relink 

The  executable  file  was  not  linked  with  the  version  of  LINK  released  with  this  version  of 
the  CodeView  debugger.  Relink  with  the  appropriate  version  of  LINK. 

Invalid  option 

An  invalid  switch  was  specified  with  the  O  command. 

Missing'"* 

A  string  specified  as  a  parameter  to  a  dialog  command  did  not  have  a  closing  double 
quotation  mark. 

Missing '(' 

A  parameter  to  a  dialog  command  was  specified  as  an  expression  containing  a  right 
parenthesis  but  no  left  parenthesis. 

Missing')' 

A  parameter  to  a  dialog  command  was  specified  as  an  expression  containing  a  left 
parenthesis  but  no  right  parenthesis. 

Missing ']' 

A  parameter  to  a  dialog  command  was  specified  as  an  expression  containing  a  left  bracket 
but  no  right  bracket,  or  a  regular  expression  was  specified  with  a  right  bracket  but  no  left 
bracket. 

Missing '('  in  complex  constant 

An  opening  parenthesis  of  a  complex  constant  in  an  expression  was  expected  but  was  not 
found. 

Missing ')'  in  complex  constant 

A  closing  parenthesis  of  a  complex  constant  in  an  expression  was  expected  but  was  not 
found. 

Missing ')'  in  substring 

A  closing  parenthesis  of  a  substring  expression  was  expected  but  was  not  found. 
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Missing '('  to  intrinsic 

An  opening  parenthesis  for  an  intrinsic  function  was  expected  but  was  not  found. 

Missing ')'  to  intrinsic 

A  closing  parenthesis  for  an  intrinsic  function  was  expected  but  was  not  found. 

No  closing  single  quote 

A  character  was  specified  in  an  expression  used  as  a  dialog-command  parameter,  but  the 
closing  single  quotation  mark  is  missing. 

No  code  at  this  line  number 

A  breakpoint  was  set  on  a  source  line  that  does  not  correspond  to  machine  code.  (In  other 
words,  the  source  line  does  not  contain  an  executable  statement.)  For  example,  the  line 
might  be  a  data  declaration  or  a  comment. 

No  free  EMM  memory  handles 

CodeView  could  not  find  an  available  EMM  handle.  Expanded  Memory  Manager  (EMM) 
software  allocates  a  fixed  number  of  memory  handles  (usually  256)  to  be  used  for  specific 
tasks. 

No  match  of  regular  expression 

No  match  was  found  for  the  regular  expression  specified  with  the  Search  (S)  dialog  com¬ 
mand  or  with  the  Find . . .  command  from  the  Search  menu. 

No  previous  regular  expression 

The  Previous  command  was  selected  from  the  Search  menu,  but  CodeView  found  no 
previous  match  for  the  last  regular  expression  specified. 

No  source  lines  at  this  address 

The  address  specified  as  a  parameter  for  the  V  dialog  command  does  not  have  any  source 
lines.  For  example,  it  could  be  an  address  in  a  library  routine  or  an  assembly-language 
module. 

No  such  file/directory 

The  specified  file  or  directory  does  not  exist. 

No  symbolic  information 

The  executable  file  specified  is  not  in  the  CodeView  format.  The  program  cannot  be 
debugged  in  source  mode  unless  the  file  is  created  in  the  CodeView  format.  The  program 
can  be  debugged  in  assembly  mode. 

Not  an  executable  file 

The  file  specified  to  be  debugged  when  CodeView  started  is  not  an  executable  file  with  a 
.EXE  or  .COM  extension. 

Notatextfile 

An  attempt  was  made  to  load  a  file  with  the  Open . . .  command  from  the  File  menu  or 
with  the  V  dialog  command,  but  the  file  is  not  a  text  file.  CodeView  determines  if  a  file  is  a 
text  file  by  checking  the  first  128  bytes  for  characters  that  are  not  in  the  ASCII  ranges  9 
through  13  and  20  through  126. 
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Not  enough  space 

The !  dialog  command  or  the  DOS  Shell  command  from  the  File  menu  was  chosen,  but 
free  memory  is  insufficient  to  execute  COMMAND.COM.  Because  memory  is  released  by 
code  in  the  FORTRAN  startup  routines,  this  error  always  occurs  if  the !  command  is  used 
before  executing  any  code.  Use  any  of  the  code-execution  dialog  commands  (T,  P,  or  G)  to 
execute  the  FORTRAN  startup  code;  then  try  the !  command  again.  This  message  also 
occurs  with  assembly-language  programs  that  do  not  specifically  release  memory. 

Object  too  big 

A  TP?  dialog  command  was  entered  with  a  data  object  (such  as  an  array)  that  is  larger  than 
128  bytes. 

Operand  types  incorrect  for  this  operation 

An  operand  in  a  FORTRAN  expression  had  a  type  incompatible  with  the  operation 
applied  to  it.  For  example,  if  P  is  declared  as  CHARACTER  P  (10),  then  ?P+5  would  pro¬ 
duce  this  error,  because  a  character  array  cannot  be  an  operand  of  an  arithmetic  operator. 

Operator  must  have  a  struct/union  type 

One  of  the  C  member-selection  operators  (-,  >,  or .)  was  used  in  an  expression  that  does 
not  reference  an  element  of  a  structure  or  union. 

Operator  needs  lvalue 

An  expression  was  specified  that  does  not  evaluate  to  a  memory  location  in  an  operation 
that  requires  one.  (An  lvalue  is  an  expression  that  refers  to  a  memory  location.)  For  exam¬ 
ple,  buffer  (count)  is  correct;  it  represents  a  symbol  in  memory.  However,  /  ,EQV.  10 
is  invalid  because  it  evaluates  to  TRUE  or  FALSE  instead  of  to  a  single  memory  location. 

Overlay  not  resident 

An  attempt  was  made  to  unassemble  machine  code  from  a  function  that  is  currently  not  in 
memory. 

Program  terminated  normally  Qexitcode') 

The  program  terminated  execution  normally.  The  number  displayed  in  parentheses  is  the 
exit  code  returned  to  MS-DOS  by  the  program. 

Radix  must  be  between  2  and  36  inclusive 

A  radix  that  is  outside  the  allowable  range  was  specified. 

Register  variable  out  of  scope 

An  attempt  was  made  to  specify  a  register  variable  by  using  the  period  (.)  operator  and  a 
routine  name. 

Regular  expression  too  complex 

The  regular  expression  specified  is  too  complex  for  CodeView  to  evaluate. 

Regular  expression  too  long 

The  regular  expression  specified  is  too  long  for  CodeView  to  evaluate. 

Restart  program  to  debug 

The  program  being  debugged  has  executed  to  the  end. 
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Simple  variable  cannot  have  argument 

A  parameter  to  a  simple  variable  was  specified  in  an  expression.  For  example,  given  the 
declaration  INTEGER  NUM,  the  expression  NUM(I)  is  not  allowed. 

Substring  range  out  of  bound 

A  character  expression  exceeded  the  length  specified  in  the  CHARACTER  statement. 

Syntax  error 

An  invalid  command  line  was  specified  for  a  dialog  command,  or  an  invalid  assembly- 
language  instruction  was  entered  with  the  A  dialog  command. 

Too  few  array  bounds  given 

The  bounds  specified  in  an  array  subscript  do  not  match  the  array  declaration.  For  exam¬ 
ple,  given  the  array  declaration  INTEGER  IARRAY(3, 4),  the  expression  lARRAYQ)  would 
produce  this  error  message. 

Too  many  array  bounds  given 

The  bounds  specified  in  an  array  subscript  do  not  match  the  array  declaration.  For  exam¬ 
ple,  given  the  array  declaration  INTEGER  I ARRAY(3AX  the  expression  I  ARRAY  (I,3J) 
would  produce  this  error  message. 

Too  many  breakpoints 

An  attempt  was  made  to  specify  more  than  20  breakpoints;  CodeView  permits  only  20. 

Too  many  files 

Too  few  file  handles  were  specified  for  CodeView  to  operate  correctly.  Specify  more  files 
in  your  CONFIG.SYS  file. 

Type  clash  in  function  argument 

The  type  of  an  actual  parameter  does  not  match  the  corresponding  formal  parameter,  or  a 
subroutine  that  uses  alternate  returns  was  called  and  the  values  of  the  return  labels  in  the 
actual  parameter  list  are  not  0. 

Type  conversion  too  complex 

An  attempt  was  made  to  typecast  an  element  of  an  expression  in  a  type  other  than  the  sim¬ 
ple  types  or  with  more  than  one  level  of  indirection.  An  example  of  a  complex  type  would 
be  typecasting  to  a  struct  or  union  type.  An  example  of  two  levels  of  indirection  is  char**. 

Unable  to  open  file 

A  file  specified  in  a  command  parameter  or  in  response  to  a  prompt  cannot  be  opened. 

Unknown  symbol 

An  identifier  that  is  not  in  CodeView’s  symbol  table  was  specified,  or  a  local  variable  was 
used  in  a  parameter  when  not  in  the  routine  where  the  variable  is  defined,  or  a  subroutine 
that  uses  alternate  returns  was  called  and  the  values  of  the  return  labels  in  the  parameter 
list  are  not  0. 

Unrecognized  optionoption 

Valid  options:  /B  /C<command>  /D  /E  /F  /I  /M  /P  /R  /S  /T  /W  /43  /2 

An  invalid  switch  was  entered  when  starting  CodeView. 
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Usage:  cv  [options]  file  [arguments] 

An  executable  file  was  not  specified  when  starting  CodeView. 

Video  mode  changed  without  /$  option 

The  program  changed  video  modes  (either  to  or  from  graphics  modes)  when  screen 
swapping  was  not  specified.  Use  the  /S  option  to  specify  screen  swapping  when  debug¬ 
ging  graphics  programs.  Debugging  can  be  continued  after  receiving  this  message,  but  the 
output  screen  of  the  debugged  program  may  be  damaged. 

Warning:  packed  file 

CodeView  was  started  with  a  packed  file  as  the  executable  file.  The  program  cannot  be 
debugged  in  source  mode  because  all  symbolic  information  is  stripped  from  a  file  when  it 
is  packed  with  LINK’S  /EXEPACK  option  or  the  EXEPACK  utility.  Try  to  debug  the  pro¬ 
gram  in  assembly  mode.  (The  packing  routines  at  the  start  of  the  program  might  make 
this  difficult.) 

Wrong  number  of  function  arguments 

An  incorrect  number  of  parameters  was  specified  when  evaluating  a  function  in  a 
CodeView  expression. 


Section  IV:  Programming  Utilities  1 173 


;<s;4?; 


System  Calls  Introduction 


Introduction 


All  versions  of  MS-DOS  include  operating-system  services  that  provide  the  programmer 
with  hardware-independent  tools  for  handling  such  tasks  as  file  management,  device  input 
and  output,  memory  allocation,  and  getting  and  setting  system-management  information 
such  as  the  date  and  time.  The  majority  of  these  services,  collectively  called  the  MS-DOS 
system  calls,  are  invoked  through  Interrupt  21H.  A  few  others  are  called  using  Interrupts 
20H  through  27H  and  2FH.  This  section  includes  descriptions  of  these  system-management 
services,  with  details  relevant  to  all  releases  of  MS-DOS  through  version  3.2. 

Use  of  the  Interrupt  21H  system  calls,  rather  than  hardware-specific  routines,  helps  ensure 
that  a  program  will  run  on  any  computer  running  an  appropriate  version  of  MS-DOS. 
Likewise,  because  new  releases  of  MS-DOS  attempt  to  maintain  compatibility  with  earlier 
versions,  use  of  the  calls  increases  the  likelihood  that  a  program  will  remain  usable  for 
more  than  a  single  major  or  minor  release  of  the  operating  system. 

The  MS-DOS  Interrupt  21H  system  calls  are  invoked  as  follows: 

AH  =  function  number 

AL  =  subfunction  code  (if  required) 

Other  registers  =  additional  function-specific  information 

Execute  Interrupt  21H 


Version  Differences 

With  MS-DOS  versions  2.0  and  later,  considerable  overlap  occurs  in  the  way  in  which 
many  system  services,  such  as  file  and  character  device  I/O,  can  be  carried  out.  This  over¬ 
lap  is  a  result  of  the  manner  in  which  MS-DOS  has  developed  since  it  was  first  released. 

The  earliest  version  of  MS-DOS,  1.0,  included  a  relatively  small  set  of  Interrupt  21H  system 
calls  designed  primarily  for  CP/M  compatibility.  These  calls,  numbered  OOH  through  2DH, 
relied  on  the  use  of  file  control  blocks  (FCBs)  in  an  application’s  memory  space  for  infor¬ 
mation  on  open  files.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Program¬ 
ming  FOR  MS-DOS:  File  and  Record  Management;  Appendix  G:  File  Control  Block  (FCB) 
Structure.  The  FCB-based  system  calls  in  MS-DOS  do  not  support  hierarchical  file  struc¬ 
tures,  nor  do  they  support  redirection  of  input  and  output.  As  a  result,  many  of  these  sys¬ 
tem  calls  have  been  superseded  in  later  releases  of  MS-DOS.  The  CP/M-style  calls  are  no 
longer  recommended  and  should  not  be  used  unless  program  compatibility  with  versions 
1.x  is  required. 

Beginning  with  version  2.0,  MS-DOS  introduced  the  concept  of  handles — l6-bit  numbers 
returned  by  the  operating  system  after  a  successful  open  or  create  call.  The  handles  can 
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subsequently  be  used  by  an  application  program  to  reference  an  open  file  or  device, 
eliminating  redundancy  and  unnecessary  overhead.  These  handles  are  also  used  inter¬ 
nally  by  MS-DOS  to  keep  track  of  open  files  and  devices.  The  operating  system  keeps  all 
such  handle-related  information  in  its  own  memory  space.  Handles  offer  full  support  for 
the  hierarchical  file  system  introduced  in  version  2.0  of  MS-DOS  and  thus  allow  the  pro¬ 
grammer  to  access  any  file  stored  in  any  directory  or  subdirectory  on  a  block  device. 
Because  of  the  increased  flexibility  offered  by  the  handle-related  system  function  calls, 
these  services  are  recommended  over  the  earlier  FCB-based  calls,  which  perform  similar 
tasks  but  for  the  current  directory  only.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRON¬ 
MENT:  Programming  for  ms-dos:  File  and  Record  Management. 

Another  advantage  of  using  the  system  calls  introduced  in  versions  2.0  and  later  is  that 
these  calls  set  the  carry  flag  when  an  operational  error  occurs  and  return  an  error  code  in 
AX  that  indicates  the  nature  of  the  error;  the  error  can  then  be  investigated  further  by  call¬ 
ing  Function  59H  (Get  Extended  Error  Information).  The  earlier  system  calls  (OOH  through 
2DH)  generally  simply  return  OFFH  (255)  in  AL  to  indicate  an  error  or  OOH  to  indicate  that 
the  call  was  completed  successfully. 


Format  of  Entries 

Entries  in  this  section  are  arranged  in  hexadecimal  order,  with  decimal  equivalents  in 
parentheses.  Each  entry  is  organized  as  follows: 

•  Hexadecimal  interrupt  and/or  function  number  (decimal  equivalent  in  parentheses) 

•  Interrupt  or  function  name  (similar  to,  but  not  always  the  same  as,  the  name  used  in 
MS-DOS  documentation) 

•  Version  dependencies 

•  Interrupt  or  function  purpose 

•  Register  contents  needed  to  call 

•  Register  contents  on  return 

•  Notes  for  programmers 

•  Related  functions 

•  Program  example 

The  format  of  these  entries  is  designed  to  give  programmers  ready  reference  to  specific 
information,  such  as  register  contents,  as  well  as  more  detailed  notes  on  the  use  and  appli¬ 
cation  of  each  system  call.  For  further  information  on  the  use  of  the  system  calls,  see 
PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT. 

The  assembly-language  examples  in  this  section  use  the  Cmacros  capability  introduced 
with  the  Windows  Software  Development  Kit.  Cmacros,  a  set  of  assembly-language  macros 
defined  in  the  file  CMACROS.INC,  are  useful  because  they  provide  a  simplified  interface  to 
the  function  and  segment  conventions  of  high-level  languages  such  as  Microsoft  C  and 
Microsoft  Pascal. 
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Advantages  to  using  Cmacros  for  assembly-language  programming  include  transparent 
support  for  memory  models  and  symbolic  names  for  function  arguments  and  local  vari¬ 
ables.  Cmacros  exist  for  code  and  data  segment  declarations  {sBegin  and  sEnd),  storage 
allocation  (staticX,  globalX,  externX,  and  labelX),  function  declarations  icProc,  parmX, 
localX,  cBegin  and  cEnd),  function  calls  (^cCall,  Save,  and  Ar^,  special  definitions 
iDefX,  RegPtr,  and  FarPtr),  and  error  control  (errnz  and  errn$).  Of  these,  only  sBegin, 
sEnd,  cProc,  parmX,  localX,  cBegin,  and  cEnd  are  used  in  the  examples  in  this  section. 

Two  additional  macros  that  support  functions  not  found  in  CMACROS.INC  are  loadCP  and 
loadDP.  These  macros,  included  in  the  file  CMACROSX.INC  listed  below,  allow  pointers 
previously  declared  with  staticX,  globalX,  parrriX,  DefX  and  localX  to  be  loaded  into 
registers  without  regard  to  the  memory  model  in  use — loadCP  and  loadDP  generate 
code  to  load  either  the  offset  portion  or  the  full  segmentioffset  of  the  address,  depending 
on  the  memory  model. 

;  CMACROSX.INC 

;  This  file  includes  supplemental  macros  for  two  macros  included 

;  in  CMACROS.INC:  parmCP  and  parmDP.  When  these  macros  are  used, 

;  CMACROS.INC  allocates  either  1  or  2  words  to  the  variables 

;  associated  with  these  macros,  depending  on  the  memory  model  in 

;  use.  However,  parmCP  and  parmDP  provide  no  support  for  automatically 

;  adjusting  for  different  memory  models -additional  program  code 

;  needs  to  be  written  to  compensate  for  this.  The  loadCP  and  loadDP 

;  macros  included  in  this  file  can  be  used  to  provide  additional 

;  flexibility  for  overcoming  this  limit. 

;  For  example,  "parmDP  pointer"  will  make  space  (1  word  in  small 

;  and  middle  models  and  2  words  in  compact,  large,  and  huge  models) 

;  for  the  data  pointer  named  "pointer".  The  statement 

;  "loadDP  ds,bx, pointer"  can  then  be  used  to  dynamically  place  the 

;  value  of  "pointer"  into  DS:BX,  depending  on  the  memory  model. 

;  In  small-model  programs,  this  macro  would  generate  the  instruction 

;  "mov  dx, pointer"  (it  is  assumed  that  DS  already  has  the  right 

;  segment  value) ;  in  large-model  programs,  this  macro  would  generate 

;  the  statements  "mov  ds, SEG_pointer"  and  "mov  dx,OFF_pointer" . 


checkDS  macro  segmt 

diff count  =  0 

irp  d, <ds, DS, Ds, dS>  ;  Allow  for  all  spellings 

ifdif  <segmt>,<d>  ;  of  "ds". 

diffcount  =  diffcount+1 
endif 
endm 

if  diffcount  EQ  4 
it_is_DS  =  0 
else 

it_is_DS  =  1 
endif 
endm 


(more) 
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checkES  macro  segmt 

diffcount  =  0 
irp  d, <es, ES, Es, eS> 
ifdif  <segmt>,<d> 

diffcount  =  diffcount+1 
endif 
endm 

if  diffcount  EQ  4 
it_is_ES  =  0 
else 

it_is_ES  =  1 
endif 
endm 

loadDP  macro  segmt, of fst, dptr 

checkDS  segmt 
if  sizeD 

if  it_is_DS 

Ids  offst,dptr 
else 

checkES  segmt 
if  it_is_ES 

les  offst,dptr 
else 

mov  offst,OFF_&dptr 
mov  segmt, SEG_&dptr 
endif 
endif 
else 

mov  offst,dptr 
if  it_is_DS  EQ  0 
push  ds 
pop  segmt 
endif 
endif 
endm 

loadCP  macro  segmt, off st, cptr 

if  sizeC 

checkDS  segmt 
if  it_is_DS 

Ids  offst,cptr 
else 

checkES 
if  it_is_ES 

les  offst,cptr 
else 

mov  segmt, SEG_& cptr 
mov  of fst, OFF_&cptr 
endif 
endif 
else 


;  Allow  for  all  spellings 
;  of  "es". 


;  < —  Large  data  model 


;  < —  Small  data  model 

;  If  "segmt"  is  not  DS, 
;  move  ds  to  segmt. 


;  < —  Large  code  model 


(more) 
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push  cs  ;  < —  Small  code  model 

pop  segmt 
mov  offst,cptr 
endif 
endm 


The  following  example  program  demonstrates  the  use  of  Cmacros  in  an  assembly- 
language  program: 


memS  =  0 

?PLM  =  0 

?WIN  =  0 


/Small  memory  model 
;C  calling  conventions 
/Disable  Windows  support 


include  cmacros. inc 
include  cmacrosx.inc 

sBegin  CODE  /Start  of  code  segment 

assumes  CS,CODE  /Required  by  MASM 


Microsoft  C  function  syntax: 

int  addnums (firstnum,  secondnum) 
int  firstnum,  secondnum/ 

Returns  firstnum  +  secondnum 


cProc 

addnums, PUBLIC 

/Start  of  addnums  functions 

parmW 

firstnum 

/Declare  parameters 

parmW 

secondnum 

cBegin 

mov  ax, firstnum 

add  ax, secondnum 

cEnd 

sEnd 

CODE 

end 

A  simple  C  program  to  call  this  function  would  be 


main  ( ) 

{ 

print f ("The  sum  is  %d", addnums (1 2, 33) ) / 

} 


Contents  by  Functional  Group 

Although  distinguishing  between  FCB-based  and  handle-based  system  calls  provides  a 
broad  and  very  generalized  means  of  categorizing  these  services,  the  more  common  and 
useful  approach  is  to  group  the  calls  by  the  type  of  task  they  perform.  The  following  list 
groups  the  Interrupt  21H  system  calls  and  Interrupts  20H,  22H  through  27H,  and  2FH  by 
type  of  service. 
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Function 

Purpose 

Character  Input 

OlH 

Character  Input  with  Echo 

03H 

Auxiliary  Input 

06H 

Direct  Console  I/O 

07H 

Unfiltered  Character  Input  Without  Echo 

OSH 

Character  Input  Without  Echo 

OAH 

Buffered  Keyboard  Input 

OBH 

Check  Keyboard  Status 

OCH 

Flush  Buffer,  Read  Keyboard 

Character  Output 

02H 

Character  Output 

04H 

Auxiliary  Output 

05H 

Print  Character 

06H 

Direct  Console  I/O 

09H 

Display  String 

Disk  Management 

ODH 

Disk  Reset 

OEH 

Select  Disk 

19H 

Get  Current  Disk 

IBH 

Get  Default  Drive  Data 

ICH 

Get  Drive  Data 

2EH 

Set/Reset  Verify  Flag 

36H 

Get  Disk  Free  Space 

54H 

Get  Verify  Flag 

File  Management 

OFH 

Open  File  with  FCB 

lOH 

Close  File  with  FCB 

IIH 

Find  First  File 

12H 

Find  Next  File 

13H 

Delete  File 

16H 

Create  File  with  FCB 

17H 

Rename  File 

lAH 

Set  DTA  Address 

23H 

Get  File  Size 

2FH 

Get  DTA  Address 

3CH 

Create  File  with  Handle 

3DH 

Open  File  with  Handle 

3EH 

Close  File 

(more) 
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Function 

Purpose 

File  Management 

(continued) 

41H 

Delete  File 

43H 

Get/Set  File  Attributes 

45H 

Duplicate  File  Handle 

46H 

Force  Duplicate  File  Handle 

4EH 

Find  First  File 

4FH 

Find  Next  File 

56H 

Rename  File 

57H 

Get/Set  Date/Time  of  File 

5AH 

Create  Temporary  File 

5BH 

Create  New  File 

5CH 

Lock/Unlock  File  Region 

Information  Management 

14H 

Sequential  Read 

15H 

Sequential  Write 

21H 

Random  Read 

22H 

Random  Write 

24H 

Set  Relative  Record 

27H 

Random  Block  Read 

28H 

Random  Block  Write 

3FH 

Read  File  or  Device 

40H 

Write  File  or  Device 

42H 

Move  File  Pointer 

Interrupt  25H 

Absolute  Disk  Read 

Interrupt  26H 

Absolute  Disk  Write 

Directory  Mam^ement 

39H 

Create  Directory 

3AH 

Remove  Directory 

3BH 

Change  Current  Directory 

47H 

Get  Current  Directory 

Process  Management 

OOH 

Terminate  Process 

31H 

Terminate  and  Stay  Resident 

4BH 

Load  and  Execute  Program  (EXEC) 

4CH 

Terminate  Process  with  Return  Code 

4DH 

Get  Return  Code  of  Child  Process 

59H 

Get  Extended  Error  Information 

Interrupt  20H  . 

Terminate  Program 

Interrupt  27H 

Terminate  and  Stay  Resident 

(more) 
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Function 

Purpose 

Memory  Management 

48H 

Allocate  Memory  Block 

49H 

Free  Memory  Block 

4AH 

Resize  Memory  Block 

58H 

Get/Set  Allocation  Strategy 

Miscellaneous  System  Management 

25H 

Set  Interrupt  Vector 

26H 

Create  New  Program  Segment  Prefix 

29H 

Parse  Filename 

2AH 

Get  Date 

2BH 

Set  Date 

2CH 

Get  Time 

2DH 

Set  Time 

30H 

Get  MS-DOS  Version  Number 

33H 

Get/Set  Control-C  Check  Flag 

34H 

Return  Address  of  InDOS  Flag 

35H 

Get  Interrupt  Vector 

38H 

Get/Set  Current  Country 

44H 

lOCTL 

5EH 

Network  Machine  Name/Printer  Setup 

5FH 

Get/Make  Assign  List  Entry 

62H 

Get  Program  Segment  Prefix  Address 

63H 

Get  Lead  Byte  Table  (version  2.25  only) 

Interrupt  22H 

Terminate  Routine  Address 

Interrupt  23H 

Control-C  Handler  Address 

Interrupt  24H 

Critical  Error  Handler  Address 

Interrupt  2FH 

Multiplex  Interrupt 
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Interrupt  20H 


InteiTupt20H(32)  1.0  and  later 

Terminate  Program 


Interrupt  20H  is  one  of  several  methods  that  a  program  can  use  to  perform  a  final  exit.  It 
informs  the  operating  system  that  the  program  is  completely  finished  and  that  the  memory 
the  program  occupied  can  be  released. 

ToCaU 

CS  =  segment  address  of  program  segment  prefix  (PSP) 

Returns 

Nothing 

Programmer’s  Notes 

•  In  response  to  an  Interrupt  20H  call,  MS-DOS  takes  the  following  actions: 

-  Restores  the  termination  handler  vector  (Interrupt  22H)  from  PSPiOOOAH. 

-  Restores  the  Control-C  vector  (Interrupt  23H)  from  PSP:000EH. 

-  With  MS-DOS  versions  2.0  and  later,  restores  the  critical  error  handler  vector  (Inter¬ 
rupt  24H)  from  PSP:0012H. 

-  Flushes  the  file  buffers. 

-  Transfers  to  the  termination  handler  address. 

The  termination  handler  releases  all  memory  blocks  allocated  to  the  program,  includ¬ 
ing  its  environment  block  and  any  dynamically  allocated  blocks  that  were  not  pre¬ 
viously  explicitly  released;  closes  any  files  opened  with  handles  that  were  not 
previously  closed;  and  returns  control  to  the  parent  process  (usually 
COMMAND.COM). 

•  If  the  program  is  returning  to  COMMAND.COM,  control  transfers  first  to 
COMMAND.COM’s  resident  portion,  which  reloads  COMMAND. COM’s  transient 
portion  (if  necessary)  and  passes  control  to  it.  If  a  batch  file  is  in  progress,  the  next 
line  of  the  batch  file  is  then  fetched  and  interpreted;  otherwise,  a  prompt  is  issued  for 
the  next  user  command. 

•  Any  files  that  have  been  written  by  the  program  using  FCBs  should  be  closed  before 
using  Interrupt  20H;  otherwise,  data  may  be  lost. 

•  For  those  programmers  who  have  been  with  MS-DOS  since  its  earliest  incarnations. 
Interrupt  20H  is  the  traditional  way  to  exit  from  an  application  program.  However, 
under  versions  2.0  and  later,  the  preferred  methods  of  termination  are  Interrupt  21H 
Function  31H  (Terminate  and  Stay  Resident)  and  Interrupt  21H  Function  4CH  (Termi¬ 
nate  Process  with  Return  Code). 
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Interrupt  20H 


Example 

;  Perform  a  final  exit. 

int  20H  ;  Transfer  to  MS-DOS. 
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Interrupt  21H  Function  OOH 


Interrupt  21H  (33)  1.0  and  later 

Function  OOH  (0) 

Terminate  Process 


Function  OOH  flushes  all  file  buffers  to  disk,  terminates  the  current  process,  and  releases 
the  memory  used  by  the  process. 

ToCaU 

AH  =  OOH 

CS  =  segment  of  program’s  program  segment  prefix  (PSP) 

Returns 

Nothing 

Programmer’s  Notes 

•  The  following  interrupt  vectors  are  restored  from  the  PSP  of  the  terminated  program: 


PSP  Offset  Vector  for  Interrupt 

OAH  Interrupt  22H  (terminate  routine) 

OEH  Interrupt  23H  (Control-C  handler) 

12H  Interrupt  24H  (critical  error  handler)  (versions  2.0  and  later.) 

•  All  file  buffers  are  written  to  disk  and  all  handles  are  closed.  Control  is  then  trans¬ 
ferred  to  Interrupt  22H  (Terminate  Routine  Address). 

•  Any  file  that  has  changed  in  length  and  was  opened  with  an  FCB  should  be  closed 
before  Function  OOH  is  called.  If  such  a  file  is  not  closed,  its  length,  date,  and  time  are 
not  recorded  correctly  in  the  directory. 

•  With  versions  3.x  of  MS-DOS,  restoring  the  default  memory-allocation  strategy  used 
by  MS-DOS  is  advisable  if  that  strategy  has  been  changed  with  Function  58H  (Get/Set 
Allocation  Strategy).  Any  global  flags,  such  as  the  break  and  verify  flags,  that  affect 
system  behavior  and  that  have  been  changed  by  the  process  should  also  be  restored 
to  their  original  values. 

•  Function  OOH  performs  exactly  the  same  processing  as  Interrupt  20H  (Terminate 
Program). 

•  Function  OOH  is  obsolete  with  MS-DOS  versions  2.0  and  later.  Function  31H  (Termi¬ 
nate  and  Stay  Resident)  and  Function  4CH  (Terminate  Process  with  Return  Code)  are 
preferred;  both  enable  the  terminating  process  to  pass  a  return  code  to  the  calling 
process  and  do  not  require  that  CS  contain  the  PSP  address. 
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Interrupt  21H  Function  OOH 


Related  Functions 

31H  (Terminate  and  Stay  Resident) 

4CH  (Terminate  Process  with  Return  Code) 

Example 

None 
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Interrupt  21H  Function  OlH 


Interrupt  21H  (33)  1.0  and  later 

Function  OlH  (1) 

Character  Input  with  Echo 


Function  OlH  waits  for  a  character  from  standard  input,  echoes  it  to  standard  output,  and 

returns  the  character  in  the  AL  register. 

ToCaU 

AH  =  OlH 

Returns 

AL  =  8-bit  character  code 

Programmer’s  Notes 

•  With  versions  1.x  of  MS-DOS,  Function  OlH  reads  input  from  the  keyboard.  With 
versions  2.0  and  later.  Function  OlH  reads  a  character  from  standard  input,  which 
defaults  to  the  keyboard  but  can  be  redirected  to  another  device  or  to  a  file.  Whether 
or  not  input  has  been  redirected,  the  character  is  echoed  to  standard  output. 

•  Function  OlH  waits  for  input  if  a  character  is  not  available.  A  wait  can  be  avoided  by 
calling  Function  OBH  (Check  Keyboard  Status),  which  checks  whether  a  character  is 
available  from  standard  input,  and  then  calling  Function  OlH  if  a  character  is  ready. 

•  On  IBM  PCs  and  compatibles,  extended  characters,  such  as  those  produced  by  the 
Alt-O  and  F8  keys,  are  returned  as  2  bytes.  The  first  byte,  OOH,  signals  an  extended 
character;  the  second  byte  completes  the  key  code.  To  read  these  characters,  Function 
OlH  must  be  called  twice. 

With  MS-DOS  versions  2.0  and  later,  if  standard  input  has  been  redirected,  the  value 
OOH  can  also  represent  a  null  character  from  a  file  and,  in  that  case,  might  not  repre¬ 
sent  valid  data.  A  program  can  use  Function  44H  (lOCTL)  Subfunction  OOH  (Get 
Device  Data)  to  determine  whether  standard  input  has  been  redirected. 

•  The  carriage-return  character  (ODH)  echoes  a  carriage  return  but  not  a  linefeed. 
Likewise,  the  linefeed  character  (OAH)  does  not  echo  a  carriage  return. 

•  With  MS-DOS  versions  2.0  and  later.  Function  OlH  cannot  detect  an  end-of-file  condi¬ 
tion  if  input  has  been  redirected. 

•  Interrupt  23H  (Control-C  Handler  Address)  is  called  if  Control-C  (03H)  is  the  input 
character  and  (with  versions  2.0  and  later)  input  is  not  redirected. 

•  With  MS-DOS  version  2.0  and  later,  if  standard  input  has  been  redirected  to  come 
from  a  file.  Break  must  be  enabled  for  Interrupt  23H  to  be  called  when  Control-C 
(03H)  is  the  input  character. 

•  Alternative  character  input  functions  are  06H  (Direct  Console  I/O),  07H  (Unfiltered 
Character  Input  Without  Echo),  and  08H  (Character  Input  Without  Echo).  The  four 
functions  are  related  as  follows: 
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Interrupt  21H  Function  OlH 


Waits  Echoes  to  Acts  on 

Function  for  Input  Std  Output  Control-C 

OlH  yes  yes  yes 

06H  no  no  no 

07H  yes  no  no 

OSH  yes  no  yes 

Depending  on  whether  Control-C  needs  to  be  filtered,  Function  06H,  07H,  or  OSH  can 
be  used  to  handle  character  display  separately  from  character  input. 

•  With  MS-DOS  versions  2.0  and  later,  Function  3FH  (Read  File  or  Device)  should  be 
used  in  preference  to  Function  OlH. 

Related  Functions 

06H  (Direct  Console  I/O) 

07H  (Unfiltered  Character  Input  Without  Echo) 

OSH  (Character  Input  Without  Echo) 

OAH  (Buffered  Keyboard  Input) 

OCH  (Flush  Buffer,  Read  Keyboard) 

3FH  (Read  File  or  Device) 

Example 

•  iiiiiiilf*itiilfiiiiilfillti(filiti(iiMtt******************************’¥****************f 

;  Function  01 H:  Character  Input  with  Echo  ; 

/  f 

;  int  read_kbcL_echo  ( )  ; 

/  f 

;  Returns  a  character  from  standard  input  ; 

;  after  sending  it  to  standard  output .  ; 


cProc  read_kbd_ec ho, PUBLIC 

cBegin 

mov  ah,01h 

int  21h 

mov  ah,0 

cEnd 


;  Set  function  code. 

;  Wait  for  character. 

;  Character  is  in  AL,  so  clear  high 
;  byte . 
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Interrupt  21H  Function  02H 


Interrupt  21H  (33)  1.0  and  later 

Function  02H  (2) 

Character  Output 


Function  02H  sends  a  character  to  standard  output. 

ToCaU 

AH  =  02H 

DL  =  8-bit  code  for  character  to  be  output 

Returns 

Nothing 

Programmer's  Notes 

•  With  versions  1.x  of  MS-DOS,  Function  02H  sends  a  character  to  the  active  display. 
With  MS-DOS  versions  2.0  and  later,  Function  02H  sends  the  character  to  standard 
output.  By  default,  the  output  is  sent  to  the  active  display,  but  it  can  be  redirected  to 
another  device  or  to  a  file. 

•  With  all  versions  of  MS-DOS,  displaying  a  backspace  (OSH)  moves  the  cursor  back 
one  position  but  does  not  erase  the  character  at  the  new  position. 

•  If  a  Control-C  is  detected  after  the  character  is  sent,  Interrupt  23H  (Control-C  Handler 
Address)  is  called. 

•  With  MS-DOS  versions  2.0  and  later.  Function  40H  (Write  File  or  Device)  should  be 
used  in  preference  to  Function  02H. 

Related  Functions 

06H  (Direct  Console  I/O) 

09H  (Display  String) 

40H  (Write  File  or  Device) 

Example 


Function  02H:  Character  Output 

int  disp_ch(c) 
char  c; 

Returns  0. 


(more) 
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Interrupt  21H  Function  02H 


cProc 

disp- 

_ch, PUBLIC 

parmB 

c 

cBegin 

mov 

dl,c 

;  Get  character  into  DL 

mov 

ah,02h 

;  Set  function  code. 

int 

21h 

;  Send  character. 

xor 

ax,  ax 

;  Return  0. 

cEnd 
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Interrupt  21H  Function  03H 


Interrupt  21H  (33)  1 0  and  later 

Function  03H  (3) 

Auxiliary  Input 


Function  03H  waits  for  a  character  from  the  standard  auxiliary  device  and  returns  the 

character  in  the  AL  register. 

ToCaU 

AH  =  03H 

Returns 

AL  =  8-bit  character  code 

Programmer’s  Notes 

•  With  versions  1.x  of  MS-DOS,  Function  03H  reads  a  character  from  the  first  serial  port. 
With  versions  2.0  and  later,  Function  03H  reads  from  the  standard  auxiliary  device 
(ALDO,  which  defaults  to  COMl. 

•  Function  03H  waits  for  input  until  a  character  is  available  from  the  standard  auxiliary 
device. 

•  Function  03H  is  not  interrupt  driven  and  does  not  buffer  characters  received  from  the 
standard  auxiliary  device.  As  a  result,  it  may  not  be  fast  enough  for  some  telecom¬ 
munications  applications  and  data  may  be  lost. 

•  A  program  cannot  perform  error  detection  using  Function  03H.  On  IBM  PCs  and  com¬ 
patibles,  error  detection  is  available  through  the  ROM  BIOS  Interrupt  14H.  Another 
option  is  to  drive  the  communications  controller  directly. 

•  Function  03H  does  not  ensure  that  auxiliary  input  is  connected  and  working,  nor  does 
it  perform  any  error  checking  or  set  up  the  auxiliary  input  device.  On  IBM  PCs  and 
compatibles,  the  standard  auxiliary  device,  normally  COMl,  is  set  to  2400  baud,  no 
parity,  1  stop  bit,  and  8  databits  at  startup.  These  parameters  can  be  changed  with  the 
MS-DOS  MODE  command. 

•  Some  auxiliary  input  devices  do  not  support  8-bit  data  transmission.  This  transmission 
parameter  is  a  characteristic  of  the  device  and  the  communication  parameters  to 
which  it  is  set;  it  is  independent  of  Function  03H. 

•  If  a  Control-C  is  detected  at  the  console.  Interrupt  23H  (Control-C  Handler  Address) 
is  called. 

•  With  MS-DOS  versions  2.0  and  later.  Function  3FH  (Read  File  or  Device),  which  han¬ 
dles  strings  as  well  as  single  characters,  should  be  used  in  preference  to  Function  03H. 

Related  Functions 

04H  (Auxiliary  Output) 

3FH  (Read  File  or  Device) 
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Interrupt  21H  Function  03H 


cProc  aux_in, PUBLIC 
cBegin 

mov  ah,03h 

int  21 h 

mov  ah, 0 

cEnd 


;  Set  function  code. 

;  Wait  for  character  from  AUX. 
;  Character  is  in  AL 
;  so  clear  high  byte. 
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Interrupt  21H  Function  04H 


Interrupt  21H  (33)  1.0  and  later 

Function  04H  (4) 

Auxiliary  Output 


Function  04H  sends  a  character  to  the  standard  auxiliary  device. 

ToCaU 

AH  =  04H 

DL  =  8-bit  code  for  character  to  be  output 

Returns 

Nothing 

Progranuner’s  Notes 

•  With  versions  1.x  of  MS-DOS,  Function  04H  sends  a  character  to  the  first  serial  port. 
With  versions  2.0  and  later,  Function  04H  sends  the  character  to  the  standard  auxiliary 
device  (AUX),  which  defaults  to  COMl. 

•  Function  04H  does  not  ensure  that  auxiliary  output  is  connected  and  working,  nor 
does  it  perform  any  error  checking  or  set  up  the  auxiliary  output  device.  On  IBM  PCIs 
and  compatibles,  the  standard  auxiliary  device,  normally  COMl,  is  set  to  2400  baud, 
no  parity,  1  stop  bit,  and  8  databits  at  startup.  These  parameters  can  be  changed  with 
the  MS-DOS  MODE  command. 

•  Function  04H  does  not  return  the  status  of  auxiliary  output,  nor  does  it  return  an  error 
code  if  the  auxiliary  output  device  is  not  ready  for  data.  If  the  device  is  busy.  Function 
04H  waits  until  it  is  available. 

•  Interrupt  23H  (Control-C  Handler  Address)  is  called  if  a  Ck>ntrol-C  is  detected  at 
the  console. 

•  With  MS-DOS  versions  2.0  and  later.  Function  40H  (Write  File  or  Device),  which  man¬ 
ages  strings  as  well  as  single  characters,  should  be  used  in  preference  to  Function 
04H. 

Related  Functions 

03H  (Auxiliary  Input) 

40H  (Write  File  or  Device) 
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Interrupt  21H  Function  04H 


Example 


Hiittiti^ittiti****************************************************** 

Function  04H:  Auxiliary  Output 

int  aux_out(c) 
char  c; 

Returns  0. 

itiHiHi****4i**Hi*:ttHiHi**HiHiil^****ilf*******t¥*************************** 


cProc  aux_out, PUBLIC 

parmB  c 

cBegin 


mov 

dl,c 

;  Get  character  into 

DL. 

mov 

ah,04h 

;  Set  function  code. 

int 

21h 

;  Write  character  to 

AUX 

xor 

ax,  ax 

;  Return  0 . 

cEnd 
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Interrupt  21H  Function  05H 


Interrupt  21H  (33)  1.0  and  later 

Function  05H  (5) 

Print  Character 


Function  05H  sends  a  character  to  the  standard  printer. 

ToCaU 

AH  =  05H 

DL  =  8-bit  code  for  character  to  be  output 

Returns 

Nothing 

Programmer’s  Notes 

•  With  versions  1.x  of  MS-DOS,  Function  05H  sends  a  character  to  the  first  parallel  port 
(LPTl).  With  versions  2.0  and  later,  Function  05H  sends  the  character  to  the  standard 
printer  (PRN),  which  defaults  to  LPTl  unless  LPTl  has  been  reassigned  with  the  MS- 
DOS  MODE  command.  If  redirection  is  in  effect,  calls  to  this  function  send  output  to 
the  device  currently  assigned  to  LPTl. 

•  Function  OSH  does  not  return  the  status  of  the  standard  printer,  nor  does  it  return  an 
error  code  if  the  standard  printer  is  not  ready  for  characters.  If  the  printer  is  busy  or  off 
line.  Function  OSH  waits  until  it  is  available.  MS-DOS  does,  however,  perform  error 
checking  during  the  print  operation  and  send  any  error  messages  to  the  standard  error 
device  (normally  the  display). 

•  If  a  Control-C  is  detected  at  the  console.  Interrupt  23H  (Control-C  Handler  Address) 
is  called. 

•  With  MS-DOS  versions  2.0  and  later.  Function  40H  (Write  File  or  Device)  should  be 
used  in  preference  to  Function  OSH. 

Related  Function 

40H  (Write  File  or  Device) 

Example 


Function  OSH:  Print  Character 

int  print_ch(c) 
char  c; 

Returns  0. 


(more) 
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Interrupt  21H  Function  OSH 


cProc 

parmB 

cBegin 


cEnd 


print_ch, PUBLIC 
c 

mov  dl , c 

mov  ah,05h 

int  21 h 

xor  ax, ax 


;  Get  character  into  DL. 

;  Set  function  code. 

;  Write  character  to  standard  printer. 
;  Return  0 . 
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Interrupt  21H  Function  06H 


Interrupt  21H  (33)  1.0  and  later 

Function  06H  (6) 

Direct  Console  I/O 


Function  06H  reads  a  character  from  standard  input  or  writes  a  character  to  standard 

output. 

ToCaU 

AH  =  06H 

For  character  input: 

DL  =FFH 

For  character  output: 

DL  =  00-FEH  (8-bit  character  code) 

Returns 

If  DL  was  OFFH  on  call  and  a  character  was  ready: 

Zero  flag  is  clear. 

AL  =  8-bit  character  code 

If  DL  was  OFFH  on  call  and  no  character  was  ready: 

Zero  flag  is  set. 

Programmer’s  Notes 

•  With  MS-DOS  versions  1.x,  Function  06H  reads  a  character  from  the  keyboard  or 
sends  a  character  to  the  display.  With  versions  2.0  and  later,  input  and  output  can  be 
redirected;  Function  06H  reads  from  the  device  currently  assigned  to  standard  input 
or  sends  to  the  device  currently  assigned  to  standard  output. 

•  Function  06H  allows  all  possible  characters  and  control  codes  with  values  between 
OOH  and  OFEH  to  be  read  or  written  with  standard  input  and  output  and  with  no  filter¬ 
ing  by  the  operating  system.  The  rubout  character  (OFFH,  255  decimal),  however, 
cannot  be  output  with  Function  06H;  Function  02H  (Character  Output)  should  be  used 
instead. 

•  On  IBM  PCs  and  compatibles,  extended  characters,  such  as  those  produced  by  the 
Alt-O  and  F8  keys,  are  returned  as  2  bytes.  The  first  byte,  OOH,  signals  an  extended 
character;  the  second  byte  completes  the  key  code.  To  read  these  characters,  Function 
06H  must  be  called  twice. 
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Interrupt  21H  Function  06H 


With  MS-DOS  versions  2.0  and  later,  if  standard  input  has  been  redirected,  the  value 
OOH  can  also  represent  a  null  character  from  a  file  and,  in  that  case,  might  not  repre¬ 
sent  valid  data.  A  program  can  use  Function  44H  (lOCTL)  Subfiinction  OOH  (Get 
Device  Data)  to  determine  whether  standard  input  has  been  redirected. 

•  If  Function  06H  is  an  input  request  and  a  Control-C  is  read,  the  character  is  returned 
as  any  other  character  would  be.  Interrupt  23H  (Control-C  Handler  Address)  is  not 
called. 

•  With  MS-DOS  versions  2.0  and  later.  Function  3FH  (Read  File  or  Device)  and  Function 
40H  (Write  File  or  Device)  should  be  used  in  preference  to  Function  06H. 

Related  Functions 

OlH  (Character  Input  with  Echo) 

02H  (Character  Output) 

07H  (Unfiltered  Character  Input  Without  Echo) 

OSH  (Character  Input  Without  Echo) 

09H  (Display  String) 

OAH  (Buffered  Keyboard  Input) 

OCH  (Flush  Buffer,  Read  Keyboard) 

3FH  (Read  File  or  Device) 

40H  (Write  File  or  Device) 

Example 


Function  06H:  Direct  Console  I/O 


int  con_io(c) 
char  c; 

Returns  meaningless  data  if  c  is  not  OFFH, 
otherwise  returns  next  character  from 
standard  input. 


cProc 

con_io, 

.PUBLIC 

parmB 

c 

cBegin 

mov 

dl,c 

;  Get  character  into  DL. 

mov 

ah, 06h 

;  Set  function  code. 

int 

21h 

;  This  function  does  NOT 

wait 

;  input  case  (c  =  OFFH) ! 

mov 

ah,  0 

;  Return  the  contents  of 

AL. 

cEnd 
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Interrupt  21H  Function  07H 


Interrupt  21H  (33)  1.0  and  later 

Function  07H  (7) 

Unfiltered  Character  Input  Without  Echo 


Function  07H  waits  for  a  character  from  standard  input.  It  does  not  echo  the  character  to 
standard  output,  and  it  ignores  Control-C  characters. 

ToCaU 

AH  =07H 

Returns 

AL  =  8-bit  character  code 

Programmer’s  Notes 

•  With  versions  1.x  of  MS-DOS,  Function  07H  reads  input  from  the  keyboard.  With 
versions  2.0  and  later.  Function  07H  reads  a  character  from  standard  input.  Standard 
input  defaults  to  the  keyboard  but  can  be  redirected  to  another  device  or  to  a  file. 

•  Function  07H  waits  for  input  if  a  character  is  not  available.  A  wait  can  be  avoided  by 
calling  Function  OBH  (Check  Keyboard  Status),  which  checks  whether  a  character  is 
available  from  standard  input,  and  then  calling  Function  07H  if  a  character  is  ready. 

•  On  IBM  PCs  and  compatibles,  extended  characters,  such  as  those  produced  by  the 
Alt-O  and  F8  keys,  are  returned  as  2  bytes.  The  first  byte,  OOH,  signals  an  extended 
character;  the  second  byte  completes  the  key  code.  To  read  these  characters.  Function 
07H  must  be  called  twice. 

With  MS-DOS  versions  2.0  and  later,  if  standard  input  has  been  redirected,  the  value 
OOH  can  also  represent  a  null  character  from  a  file  and,  in  that  case,  might  not  repre¬ 
sent  valid  data.  A  program  can  use  Function  44H  (lOCTL)  Subfunction  OOH  (Get 
Device  Data)  to  determine  whether  standard  input  has  been  redirected. 

•  Interrupt  23H  (Control-C  Handler  Address)  is  not  called  if  a  Control-C  is  read.  Func¬ 
tion  07H  simply  passes  the  character  back  through  the  AL  register.  If  Control-C  check¬ 
ing  is  required.  Function  08H  (Character  Input  Without  Echo)  should  be  used  instead. 

•  With  MS-DOS  versions  2.0  and  later.  Function  3FH  (Read  File  or  Device)  should  be 
used  in  preference  to  Function  07H. 

Related  Functions 

OlH  (Character  Input  with  Echo) 

06H  (Direct  Console  I/O) 

08H  (Character  Input  Without  Echo) 

OAH  (Buffered  Keyboard  Input) 

OCH  (Flush  Buffer,  Read  Keyboard) 

3FH  (Read  File  or  Device) 
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Example 


Function  07H:  Unfiltered  Character  Input 
Without  Echo 


;  int  con_in() 

;  Returns  next  character  from  standard  input. 

.H:*it:4:iii:^4^4^4‘****************!¥********************************** 

cProc  con_in, PUBLIC 
cBegin 

mov  ah,07h  ;  Set  function  code. 

int  21 h  ;  Wait  for  character,  no  echo. 

mov  ah,0  ;  Clear  high  byte. 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  OSH  (8) 

Character  Input  Without  Echo 


Function  OSH  waits  for  a  character  from  standard  input.  The  character  is  not  echoed  to 
standard  output. 

ToCaU 

AH  =  OSH 

Returns 

AL  =  S-bit  character  code 

Programmer’s  Notes 

•  With  versions  1.x  of  MS-DOS,  Function  OSH  reads  input  from  the  keyboard.  With 
versions  2.0  and  later,  Function  OSH  reads  a  character  from  standard  input.  Standard 
input  defaults  to  the  keyboard  but  can  be  redirected  to  another  device  or  to  a  file. 

•  Function  OSH  waits  for  input  if  a  character  is  not  available.  A  wait  can  be  avoided  by 
calling  Function  OBH  (Check  Keyboard  Status),  which  checks  whether  a  character  is 
available,  and  then  calling  Function  OSH  if  a  character  is  ready. 

•  On  IBM  PCs  and  compatibles,  extended  characters,  such  as  those  produced  by  the 
Alt-O  and  FS  keys,  are  returned  as  2  bytes.  The  first  byte,  OOH,  signals  an  extended 
character;  the  second  byte  completes  the  key  code.  To  read  these  characters.  Function 
OSH  must  be  called  twice. 

With  MS-DOS  versions  2.0  and  later,  if  standard  input  has  been  redirected,  the  value 
OOH  can  also  represent  a  null  character  from  a  file  and,  in  that  case,  might  not  repre¬ 
sent  valid  data.  A  process  can  use  Function  44H  (lOCTL)  Subfunction  OOH  (Get 
Device  Data)  to  determine  whether  standard  input  has  been  redirected. 

•  If  a  Control-C  is  read  and  (with  versions  2.0  and  later)  input  has  not  been  redirected. 
Interrupt  23H  (Control-C  Handler  Address)  is  called.  To  read  the  Control-C  character 
as  data,  Function  07H  (Unfiltered  Character  Input  Without  Echo)  should  be  used. 

•  Interrupt  23H  (Control-C  Handler  Address)  is  called  if  Control-C  is  the  input  character. 
Break  is  enabled,  and  (with  versions  2.0  and  later)  standard  input  has  been  redirected 
to  come  from  a  file. 

•  With  MS-DOS  versions  2.0  and  later.  Function  3FH  (Read  File  or  Device)  should  be 
used  in  preference  to  Function  OSH. 

Related  Functions 

OlH  (Character  Input  with  Echo) 

06H  (Direct  Console  I/O) 

07H  (Unfiltered  Character  Input  Without  Echo) 

OAH  (Buffered  Keyboard  Input) 

OCH  (Flush  Buffer,  Read  Keyboard) 

3FH  (Read  File  or  Device) 
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Example 

t 

;  Function  08H:  Unfiltered  Character  Input  Without  Echo 

;  int  reacL_kbd() 

t 

;  Returns  next  character  from  standard  input . 

cProc  read_kbd, PUBLIC 

cBegin 

mov  ah,08h  ;  Set  function  code. 

int  21 h  ;  Wait  for  character,  no  echo. 

mov  ah, 0  ;  Clear  high  byte . 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  09H  (9) 

Display  String 


Function  09H  sends  a  string  of  characters  to  standard  output.  The  string  must  end  with  the 
dollar-sign  character  ($).  All  characters  up  to,  but  not  including,  the  $  are  displayed. 

ToCaU 

AH  =09H 

DS:DX  =  segment:offset  of  string  to  display 

Returns 


Nothing 

Programmer’s  Notes 

•  With  MS-DOS  versions  1.x,  Function  09H  sends  the  string  to  the  display.  With  versions 
2.0  and  later,  the  string  is  written  to  standard  output.  By  default,  standard  output  is 
sent  to  the  display,  but  it  can  be  redirected  to  another  device  or  to  a  file. 

•  The  string  can  include  any  valid  ASCII  characters,  including  control  codes.  Sending  a 
dollar  sign  with  this  function,  however,  is  not  possible. 

•  Depending  on  the  device  currently  serving  as  standard  output,  characters  other  than 
the  normally  displayable  ASCII  characters  (20H  to  7FH)  may  or  may  not  be  displayed. 
On  IBM  PCs  and  most  compatibles,  extensions  to  the  displayable  ASCII  character  set 
(character  codes  80H  to  FFH)  appear  as  foreign  or  graphics  characters. 

•  Display  begins  at  the  current  cursor  position  on  standard  output.  After  the  string  is 
completely  displayed,  the  cursor  position  is  updated  to  the  location  immediately 
following  the  string. 

On  IBM  PCs  and  compatibles,  if  the  end  of  a  line  is  reached  before  the  string  is  com¬ 
pletely  displayed,  a  carriage  return  and  linefeed  are  issued  and  the  next  character  is 
displayed  in  the  first  position  of  the  following  line.  If  the  cursor  reaches  the  bottom 
right  corner  of  the  display  before  the  complete  string  has  been  sent,  the  display  is 
scrolled  up  one  line. 

•  Control  characters  are  often  included  in  the  string  to  be  sent.  The  following  sample 
fragment  of  code  contains  carriage  returns  and  linefeeds: 


msg  db 
db 
db 
db 
db 


'Resident  part  of  TSR.COM  installed' 
Odh,  Oah 

'Copyright  (c)  1 9xx  Foo  Software,  Inc.' 
Odh,  Oah,  Oah,  Oah 

'$' 


•  If  a  Control-C  is  detected,  Interrupt  23H  (Control-C  Handler  Address)  is  called. 
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•  With  MS-DOS  versions  2.0  and  later,  Function  40H  (Write  File  or  Device)  should  be 

used  in  preference  to  Function  09H. 

Related  Functions 

02H  (Character  Output) 

06H  (Direct  Console  I/O) 

40H  (Write  File  or  Device) 

Example 

.*4c******Hc*«***«***********«4:4:*«**4c*******:)c:|c*************4:4:!ic:i:; 

;  Function  09H:  Display  String  ; 

;  int  disp_str (pstr)  ; 

;  char  *pstr;  ; 

;  Returns  0 .  ; 

.Hi:^^^:*********************************************************; 


cProc  disp_str, PUBLIC, <ds, di> 

parmDP  pstr 

cBegin 

loadDP  ds,dx,pstr 
mov  ax,0900h 


push  ds 

pop  es 

mov  di , dx 

mov  cx,0ffffh 

repne  scasb 

dec  di 

mov  byte  ptr  [di],'$ 

int  21  h 

mov  [di],al 

xor  ax, ax 

cEnd 


DS:DX  =  pointer  to  string. 

Prepare  to  write  dollar-terminated 
string  to  standard  output,  but 
first  replace  the  0  at  the  end  of 
the  string  with 
Set  ES  equal  to  DS . 

(MS-C  does  not  require  ES  to  be 
saved. ) 

ES:DI  points  at  string. 

Allow  string  to  be  64KB  long. 

Look  for  0  at  end  of  string. 

Scasb  search  always  goes  1  byte  too 
far. 

;  Replace  0  with  dollar  sign. 

Have  MS-DOS  print  string. 

Restore  0  terminator. 

Return  0 . 
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Interrupt  21H  (33)  1.0  and  later 

Function  OAH  (10) 

Buffered  Keyboard  Input 


Function  OAH  collects  characters  from  standard  input  and  places  them  in  a  user-specified 
memory  buffer.  Input  is  accepted  until  either  a  carriage  return  (ODH)  is  encountered  or  the 
buffer  is  filled  to  one  character  less  than  its  capacity.  The  characters  are  echoed  to  stan¬ 
dard  output. 

ToCaU 

AH  =  OAH 

DS:DX  =  segment:offset  of  input  buffer 

Returns 

Nothing 

Programmer’s  Notes 

•  With  MS-DOS  versions  1.x,  Function  OAH  reads  a  string  from  the  keyboard.  With 
versions  2.0  and  later,  calls  to  this  function  read  a  string  from  standard  input,  which 
defaults  to  the  keyboard  but  can  be  redirected  to  another  device  or  to  a  file.  The 
MS-DOS  editing  keys  are  active  during  input  with  this  function. 

•  The  buffer  pointed  to  by  DS:DX  must  have  the  following  format: 


Byte  Contents 

0  Maximum  number  of  characters  to  read  (1-255);  this  value  must  be  set 

by  the  process  before  Function  OAH  is  called. 

1  Count  of  characters  read  (does  not  include  the  carriage  return); 

this  value  is  set  by  Function  OAH  before  returning  to  the  process. 
2-(w+2)  Actual  string  of  characters  read,  including  the  carriage  return;  n  = 
number  of  bytes  read. 

•  The  first  byte  of  the  buffer  must  contain  the  maximum  number  of  characters  the 
program  will  accept,  including  the  carriage  return  at  the  end.  Because  the  last  byte 
must  be  a  carriage  return,  the  maximum  number  of  bytes  this  function  will  actually 
read  is  254.  The  carriage  return  is  not  included  in  the  character  count  returned  by 
MS-DOS  in  the  second  byte  of  the  buffer. 

•  If  the  buffer  fills  to  1  byte  less  than  its  capacity,  succeeding  characters  are  ignored  and 
a  beep  is  sounded  for  each  keypress  until  a  carriage  return  is  received. 

•  If  a  Control-C  is  detected  and  (with  versions  2.0  and  later)  input  has  not  been  redi¬ 
rected,  Interrupt  23H  (Control-C  Handler  Address)  is  called. 

•  With  versions  2.0  and  later,  if  standard  input  has  been  redirected  to  come  from  a  file. 
Break  must  be  enabled  for  Interrupt  23H  (Control-C  Handler  Address)  to  be  called 
when  Control-C  is  the  input  character. 


Section  V:  System  Calls  1207 


Interrupt  21H  Function  OAH 


•  With  MS-DOS  versions  2.0  and  later,  if  input  is  redirected,  an  end-of-file  condition 
goes  undetected  by  Function  OAH. 

Related  Functions 

OlH  (Character  Input  with  Echo) 

06H  (Direct  Console  I/O) 

07H  (Unfiltered  Character  Input  Without  Echo) 

OSH  (Character  Input  Without  Echo) 

OCH  (Flush  Buffer,  Read  Keyboard) 

3FH  (Read  File  or  Device) 

Example 


Function  OAH:  Buffered  Keyboard  Input  ; 

int  read_str (pbuf ,  len)  ; 

char  *pbuf;  ; 

int  len;  ; 

Returns  number  of  bytes  read  into  buffer.  ; 

Note:  pbuf  must  be  at  least  len+3  bytes  long.  ; 


cProc  read_str, PUBLIC, <ds,di> 


parmDP 

pbuf 

parmB 

len 

cBegin 

loadDP 

ds, dx, pbuf 

raov 

al, len 

inc 

al 

mov 

di,  dx 

mov 

[di] ,al 

mov 

ah, Oah 

int 

21h 

mov 

al, [di+1 ] 

mov 

ah,0 

mov 

bx,  ax 

mov 

[bx+di+2] , ah 

cEnd 


;  DS:DX  =  pointer  to  buffer. 

;  AL  =  len. 

;  Add  1  to  allow  for  CR  in  buf. 

;  Store  max  length  into  buffer. 

;  Set  function  code. 

;  Ask  MS-DOS  to  read  string. 

;  Return  number  of  characters  read. 


;  Store  0  at  end  of  buffer. 
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Interrupt  21H  (33)  1.0  and  later 

Function  OBH  (11) 

Check  Keyboard  Status 


Function  OBH  returns  a  value  in  AL  that  indicates  whether  a  character  is  available  from 

standard  input. 

ToCaU 

AH  =  OBH 

Returns 

AL  =  OOH  no  character  available 

FFH  one  or  more  characters  available 

Programmer's  Notes 

•  With  MS-DOS  versions  1.x,  Function  OBH  checks  the  type-ahead  buffer  for  a  char¬ 
acter.  With  versions  2.0  and  later,  if  input  has  been  redirected.  Function  OBH  checks 
standard  input  for  a  character.  If  input  has  not  been  redirected,  the  function  checks 
the  type-ahead  buffer. 

•  Function  OBH  does  not  indicate  how  many  characters  are  available;  it  merely  indicates 
whether  at  least  one  character  is  available. 

•  If  the  available  character  is  Control-C,  Interrupt  23H  (Control-C  Handler  Address)  is 
called. 

•  Function  OBH  does  not  remove  characters  from  standard  input.  Thus,  if  a  character  is 
present,  repeated  calls  return  OFFH  in  AL  until  all  characters  in  the  buffer  are  read, 
either  with  one  of  the  character-input  functions  (OlH,  06H,  07H,  OSH,  or  OAH)  or  with 
Function  3FH  (Read  File  or  Device)  using  the  handle  for  standard  input  (0). 

Related  Functions 

06H  (Direct  Console  I/O) 

44H  Subfunction  06H  (lOCTL:  Check  Input  Status) 

Example 


Function  OBH:  Check  Keyboard  Status 
int  key_ready ( ) 

Returns  1  if  key  is  ready,  0  if  not. 


(more) 
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cProc  key_ready, PUBLIC 


cBegin 

mov 

ah, Obh 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  if  key  is  available. 

and 

ax, 0001 h 

;  Keep  least  significant  bit  only 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  OCH  (12) 

Flush  Buffer,  Read  Keyboard 


Function  OCH  clears  the  standard-input  buffer  and  then  performs  one  of  the  other 

keyboard  input  functions  (OlH,  06H,  07H,  OSH,  OAH). 

ToCaU 

AH  =  OCH 

AL  =  input  function  number  to  execute 

IfAL  is  06H: 

DL  =  FFH 

IfAL  is  OAH: 

DS:DX  =  segment:offset  of  buffer  to  receive  input 

Returns 

If  AL  was  OlH,  06H,  07H,  or  OSH  on  call: 

AL  =  S-bit  ASCII  character  from  standard  input 

If  AL  was  OAH  on  call: 

Nothing 

Programmer’s  Notes 

•  With  versions  1.x  of  MS-DOS,  Function  OCH  empties  the  type-ahead  buffer  before 
executing  the  input  function  specified  in  AL.  With  versions  2.0  and  later,  if  input  has 
been  redirected  to  a  file.  Function  OCH  does  nothing  before  carrying  out  the  input 
function  specified  in  AL;  if  input  was  not  redirected,  the  type-ahead  buffer  is  flushed. 

•  A  function  number  other  than  OlH,  06H,  07H,  OSH,  or  OAH  in  AL  simply  flushes  the 
standard-input  buffer  and  returns  control  to  the  calling  program. 

•  IfAL  contains  OAH,  DS:DX  must  point  to  the  buffer  in  which  MS-DOS  is  to  place  the 
string  read  from  the  keyboard. 

•  Because  the  buffer  is  flushed  before  the  input  function  is  carried  out,  any  Control-C 
characters  pending  in  the  buffer  are  discarded.  If  subsequent  input  is  a  Control-C, 
however.  Interrupt  23H  (Control-C  Handler  Address)  is  called  if  (in  versions  2.0  and 
later)  standard  input  has  not  been  redirected  to  come  from  a  file. 

•  With  versions  2.0  and  later,  if  standard  input  has  been  redirected  to  come  from  a  file 
and,  after  the  buffer  is  flushed,  subsequent  input  is  a  Control-C  character.  Interrupt 
23H  (Control-C  handler  address)  is  called  only  if  Break  is  enabled. 

•  This  function  exists  to  defeat  the  type-ahead  feature  if  necessary — for  example,  to 
obtain  input  at  a  critical  prompt  the  user  may  not  have  anticipated. 
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Related  Functions 

OlH  (Character  Input  with  Echo) 

06H  (Direct  Console  I/O) 

07H  (Unfiltered  Character  Input  Without  Echo) 

OSH  (Character  Input  Without  Echo) 

OAH  (Buffered  Keyboard  Input) 

3FH  (Read  File  or  Device) 

Example 

;********************************♦***♦**♦****♦***************; 
;  Function  OCH:  Flush  Buffer,  Read  Keyboard  ; 

;  int  flush_kbd{)  ; 

;  Returns  0 .  ; 

.*♦♦********♦****************♦*♦***♦♦**♦*♦*******************; 

cProc  flush_kbd, PUBLIC 
cBegin 

mov  ax,0c00h  ;  Just  flush  type-ahead  buffer, 

int  21 h  ;  Call  MS-DOS. 

xor  ax, ax  ;  Return  0. 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  ODH  (13) 

Disk  Reset 


Function  ODH  writes  to  disk  all  internal  MS-DOS  file  buffers  in  memory  that  have  been 

modified  since  the  last  write.  All  buffers  are  then  marked  as  “free.” 

ToCaU 

AH  =  ODH 

Returns 

Nothing 

Programmer's  Notes 

•  Function  ODH  ensures  that  the  information  stored  on  disk  matches  changes  made  by 
write  requests  to  file  buffers  in  memory. 

•  Function  ODH  does  not  update  the  disk  directory.  The  application  must  issue  Func¬ 
tion  lOH  (Close  File  with  FCB)  or  Function  3EH  (Close  File)  to  update  directory  infor¬ 
mation  correctly. 

•  Function  ODH  should  be  part  of  Control-C  interrupt-handling  routines  so  that  the 
system  is  left  in  a  known  state  when  an  application  is  terminated. 

•  Disk  Reset  calls  can  be  issued  after  particularly  important  disk  write  calls,  such  as 
transactions  in  an  accounting  application.  Repeated  use  of  this  function,  however, 
degrades  system  performance  by  defeating  the  MS-DOS  buffering  scheme. 

Related  Functions 

lOH  (Close  File  with  FCB) 

3EH  (Close  File) 

Example 


Function  ODH:  Disk  Reset 
int  reset-disk  0 
Returns  0 . 


(more) 
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cProc  reset-disk, PUBLIC 
cBegin 

mov  ah,0dh  ;  Set  function  code. 

int  21 h  ;  Ask  MS-DOS  to  write  all  dirty  file 

;  buffers  to  the  disk, 
xor  ax, ax  ;  Return  0. 

cEnd 


1214  The  MS-DOS  Encyclopedia 


Interrupt  21H  Function  OEH 


Interrupt  21H  (33)  1.0  and  later 

Function  OEH  (14) 

Select  Disk 


Function  OEH  sets  the  default  disk  drive  to  the  drive  specified  in  the  DL  register.  The 
default  is  the  disk  drive  MS-DOS  chooses  for  file  access  when  a  filename  is  specified 
without  a  drive  designator.  A  successful  call  to  this  function  returns  the  number  of  logical 
(not  physical)  drives  in  the  system. 

ToCaU 

AH  =  OEH 

DL  =  drive  number  (0  =  drive  A,  1  =  drive  B,  2  =  drive  C,  and  so  on) 

Returns 

AL  =  number  of  logical  drives  in  the  system 

Programmer’s  Notes 

•  The  value  used  as  a  drive  number  is  the  ASCII  value  of  the  uppercase  drive  letter 
minus  the  ASCII  value  of  the  uppercase  letter  A  (4lH);  thus,  0  =  drive  A,  1  =  drive  B, 
and  so  on. 

•  A  logical  drive  is  defined  as  any  block-oriented  device;  this  category  includes  floppy- 
disk  drives,  RAMdisks,  tape  devices,  fixed  disks  (which  can  be  partitioned  into  more 
than  one  logical  drive),  and  network  drives. 

•  The  maximum  numbers  of  drive  designators  available  for  each  MS-DOS  version  are  as 
follows: 


MS-DOS  Version 

Number  of  Designators 

Values 

1.x 

16 

0  through  OFH 

2.x 

63 

0  through  3FH 

3.x 

26 

0  through  19H 

Drive  letters  should  be  limited  to  A  through  P  (0  through  OEH)  to  ensure  that  an 
application  runs  on  all  versions  of  MS-DOS. 

•  With  versions  of  MS-DOS  earlier  than  3.0  running  on  IBM  PCs  and  compatibles  with 
one  floppy-disk  drive.  Function  OEH  returns  02H  as  the  drive  count,  because  the 
single  physical  drive  is  equivalent  to  the  two  logical  drives  A  and  B.  MS-DOS  versions 
3.0  and  later  return  a  minimum  value  of  05H  in  AL. 

•  On  IBM  PCs  and  compatibles,  the  number  of  physical  floppy-disk  drives  in  a  system 
can  be  obtained  from  the  ROM  BIOS  with  Interrupt  IIH  (Equipment  Determination). 
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Related  Function 

19H  (Get  Current  Disk) 

Example 

;:»:***************♦*♦**♦*************************************♦ 
;  Function  OEH:  Select  Disk 

f 

;  int  select-drive {drive_ltr) 

;  char  drive_ltr; 

f 

;  Returns  number  of  logical  drives  present  in  system. 

i 


cProc  select-drive, PUBLIC 

parmB  drive— Itr 

cBegin 

mov  dl, drive— Itr 

and  dl,not  20h 

sub  dl, 'A' 

mov  ah,0eh 

int  21  h 

cbw 

cEnd 


Get  new  drive  letter. 

Make  sure  letter  is  uppercase. 
Convert  drive  letter  to  number, 
'A'  =  0,  'B'  =  1,  etc. 

Set  function  code. 

Ask  MS-DOS  to  set  default  drive. 
Clear  high  byte  of  return  value. 
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Interrupt  21H  (33)  1.0  and  later 

Function  OFH  (15) 

open  File  with  FCB 


Function  OFH  opens  the  file  named  in  the  file  control  block  (FCB)  pointed  to  by  DS:DX. 

ToCaU 

AH  =  OFH 

DS:DX  =  segment:offset  of  an  unopened  FCB 

Returns 

If  function  is  successful: 

AL  =  OOH 

If  function  is  not  successful: 

AL  =  FFH 

Programmer's  Notes 

•  MS-DOS  provides  several  types  of  file  services:  FCB  file  services,  which  are  relatively 
compatible  with  the  CP/M  methods  of  file  handling;  extended  FCB  file  services,  which 
take  advantage  of  both  CP/M  compatibility  and  MS-DOS  extensions;  and  handle,  or 
“stream-oriented,”  file  services,  which  are  more  compatible  with  UNIX/XENEX  and 
support  pathnames  (MS-DOS  versions  2.0  and  later). 

•  Function  OFH  does  not  support  pathnames  and  so  is  capable  of  opening  files  only  in 
the  current  directory  of  the  specified  drive. 

•  Function  OFH  does  not  create  a  new  file  if  the  specified  file  does  not  already  exist. 
Function  16H  (Create  File  with  FCB)  is  used  to  create  new  files  with  FCBs. 

•  Function  OFH  must  use  an  unopened  FCB — that  is,  one  in  which  all  but  the  drive- 
designator,  filename,  and  extension  fields  are  zero.  If  the  call  is  successful,  the  func¬ 
tion  fills  in  the  file  size  and  date  fields  from  the  file’s  directory  entry.  In  MS-DOS 
versions  2.0  and  later,  the  function  also  fills  in  the  time  field. 

•  If  the  file  is  opened  on  the  default  drive  (the  drive  number  in  the  FCB  is  set  to  0), 
MS-DOS  fills  in  the  actual  drive  code.  Thus,  at  some  later  point  in  processing,  the 
default  drive  can  be  changed  and  MS-DOS  will  still  have  the  drive  number  in  the  FCB 
for  use  in  accessing  the  file.  It  will  therefore  continue  to  use  the  correct  drive. 

•  If  Function  OFH  is  successful,  MS-DOS  sets  the  current-block  field  to  0;  that  is,  the  file 
pointer  is  at  the  beginning  of  the  file.  It  also  sets  the  record  size  to  128  bytes  (the 
system  default). 

•  If  a  record  size  other  than  128  is  needed,  the  record  size  field  of  the  FCB  should  be 
changed  after  the  file  is  successfully  opened  and  before  attempting  any  I/O. 
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•  In  a  network  running  under  MS-DOS  version  3.1  or  later,  files  are  opened  by  Function 
OFH  with  the  share  code  set  to  compatibility  mode  and  the  access  code  set  to  read/ 
write. 

•  If  Function  OFH  returns  an  error  code  (OFFH)  in  the  AL  register,  the  attempt  to  open 
the  file  was  not  successful.  Possible  causes  for  the  failure  are 

-  File  was  not  found. 

-  File  has  the  hidden  or  system  attribute  and  a  properly  formatted  extended  FCB  was 
not  used. 

-  Filename  was  improperly  specified  in  the  FCB. 

-  SHARE  is  loaded  and  the  file  is  already  open  by  another  process  in  a  mode  other 
than  compatibility  mode. 

•  With  MS-DOS  versions  3.0  and  later.  Function  59H  (Get  Extended  Error  Information) 
can  be  used  to  determine  why  the  attempt  to  open  the  file  failed. 

•  MS-DOS  passes  the  first  two  command-tail  parameters  into  default  FCBs  located  at 
offsets  5CH  and  6CH  in  the  program  segment  prefix  (PSP).  Many  applications 
designed  to  run  as  .COM  files  take  advantage  of  one  or  both  of  these  default  FCBs. 

•  With  MS-DOS  versions  2.0  and  later.  Function  3DH  (Open  File  with  Handle)  should  be 
used  in  preference  to  Function  OFH. 

Related  Functions 

lOH  (Close  File  with  FCB) 

16H  (Create  File  with  FCB) 

3CH  (Create  File  with  Handle) 

3DH  (Open  File  with  Handle) 

3EH  (Close  File) 

59H  (Get  Extended  Error  Information) 

5AH  (Create  Temporary  File) 

5BH  (Create  New  File) 

Example 


Function  OFH:  Open  File,  FCB-based  ; 

int  FCB_open (uXFCB, recsize)  ; 

char  *uXFCB;  ; 

int  recsize;  ; 

f 

Returns  0  if  file  opened  OK,  otherwise  returns  -1 .  ; 

Note:  uXFCB  must  have  the  drive  and  filename  ; 

fields  (bytes  07H  through  12H)  and  the  extension  ; 

flag  (byte  OOH)  set  before  the  call  to  FCB_open  ; 

(see  Function  29H) .  ; 

/ 

(more) 
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cProc 

parmDP 

parmW 

cBegin 


cEnd 


FCB_open, PUBLIC, ds 

puXFCB 

recsize 


loadDP 

ds, dx, puXFCB 

;  Pointer  to  unopened  extended  FCB. 

mov 

ah,0fh 

;  Ask  MS-DOS  to  open  an  existing  file 

int 

21h 

add 

dx,7 

;  Advance  pointer  to  start  of  regular 
;  FCB. 

mov 

bx,  dx 

;  BX  =  FCB  pointer. 

mov 

dx, recsize 

;  Get  record  size  parameter. 

mov 

[bx+Oeh] , dx 

;  Store  record  size  in  FCB. 

xor 

dx,  dx 

mov 

[bx+20h] ,dl 

;  Set  current-record 

mov 

[bx+21 h] , dx 

;  and  relative-record 

mov 

[bx+23h] ,dx 

;  fields  to  0. 

cbw 

;  Set  return  value  to  0  or  -1  . 
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Interrupt  21H  (33)  1.0  and  later 

Function  lOH  (16) 

Close  File  with  FCB 


Function  lOH  flushes  file-related  information  to  disk,  closes  the  file  named  in  the  file  con¬ 
trol  block  (FCB)  pointed  to  by  DS:DX,  and  updates  the  file’s  directory  entry. 

To  Call 

AH  =  lOH 

DS:DX  =  segmentioffset  of  previously  opened  FCB 

Returns 

If  function  is  successful: 

AL  =  OOH 

If  function  is  not  successful: 

AL  =  FFH 

Programmer’s  Notes 

•  A  successful  call  to  Function  lOH  flushes  to  disk  all  MS-DOS  internal  buffers  associ¬ 
ated  with  the  file  and  updates  the  directory  entry  and  file  allocation  table  (FAT).  The 
function  thus  ensures  that  correct  information  is  contained  in  the  copy  of  the  file  on 
disk. 

•  Because  MS-DOS  versions  1.x  and  2.x  do  not  always  detect  a  disk  change,  an  error 
can  occur  if  the  user  changes  disks  between  the  time  the  file  is  opened  and  the  time 
it  is  closed.  In  the  worst  case,  the  FAT  and  the  directory  of  the  newly  inserted  disk 
may  be  damaged. 

•  With  MS-DOS  versions  2.0  and  later.  Function  3EH  (Close  File)  should  be  used  in 
preference  to  Function  lOH. 

Related  Functions 

OFH  (Open  File  with  FCB) 

3EH  (Close  File) 
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Example 

;  Function  10H:  Close  file,  FCB-based 

;  int  FCB_close (oXFCB) 

;  char  *oXFCB; 

;  Returns  0  if  file  closed  OK,  otherwise 

;  returns  -1 . 

f*************4i**!¥****************^*^ittilft****^:it:Hi^it:^itit:itiH:^;^s:ti^iiiiHi^it: 

cProc  FCB_close, PUBLIC,  ds 

parmDP  poXFCB 

cBegin 

loadDP  ds,dx,poXFCB  ;  Pointer  to  opened  extended  FCB. 

file . 

0  or  -1 . 


cEnd 


mov 

int 

cbw 


ah, 1  Oh 
21h 


Ask  MS-DOS  to  close 
Set  return  value  to 
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Interrupt  21H  (33)  1.0  and  later 

Function  IIH  (17) 

Find  First  File 


Function  IIH  searches  the  current  directory  for  the  first  file  that  matches  a  specified  name 

and  extension. 

ToCaU 

AH  =  IIH 

DS:DX  =  segment:offset  of  unopened  file  control  block  (FCB) 

Returns 

If  function  is  successful: 

AL  =  OOH 

Disk  transfer  area  (DTA)  contains  unopened  FCB  of  same  type  (normal  or  extended)  as 

search  FCB. 

If  function  is  not  successful: 

AL  =  FFH 

Programmer’s  Notes 

•  If  necessary,  Function  lAH  (Set  DTA  Address)  should  be  used  before  Function  IIH  is 
called,  to  set  the  location  of  the  DTA  in  which  the  results  of  the  search  will  be  placed. 

•  With  MS-DOS  versions  1.0  and  later,  the  wildcard  character  ?  is  allowed  in  the 
filename.  With  MS-DOS  versions  3  0  and  later,  both  wildcard  characters  (?  and  ♦)  are 
allowed  in  filenames.  Pathnames  are  not  supported. 

•  With  MS-DOS  versions  2.0  and  later,  the  attribute  field  of  an  extended  FCB  can  be 
used  to  search  for  files  with  the  hidden,  system,  subdirectory,  or  volume-label  attri¬ 
butes.  In  such  a  search,  specifying  either  the  normal  (OOH)  or  volume-label  (OSH) 
attribute  restricts  MS-DOS  to  files  with  the  given  attribute.  Specifying  any  combina¬ 
tion  of  the  hidden  (02H),  system  (04H),  and  subdirectory  (lOH)  attributes,  however, 
causes  MS-DOS  to  search  both  for  normal  files  and  for  those  that  match  the  specified 
attributes. 

•  For  a  normal  FCB,  Function  IIH  places  the  drive  number  in  the  first  byte  of  the  DTA 
and  fills  the  succeeding  32  bytes  with  the  directory  entry. 

For  an  extended  FCB,  Function  IIH  fills  in  the  first  7  bytes  of  the  DTA  as  follows:  the 
first  byte  contains  OFFH,  indicating  an  extended  FCB;  the  second  through  sixth  bytes 
contain  OOH,  as  required  by  MS-DOS;  the  seventh  byte  contains  the  value  of  the  at¬ 
tribute  byte  in  the  search  FCB.  The  next  33  bytes  contain  the  drive  number  and  direc¬ 
tory  information,  as  for  a  normal  FCB. 
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•  As  with  other  FCB  functions,  the  number  0  can  be  used  to  indicate  the  default  drive. 
MS-DOS  fills  in  the  actual  drive  number  and  continues  to  use  that  drive  for  calls  to 
Function  12H  (Find  Next  File)  that  use  the  same  FCB,  regardless  of  any  subsequent 
selection  of  a  different  default  drive. 

•  The  FCB  with  the  initial  file  specifications  must  remain  unmodified  if  Function  12H  is 
used  to  continue  the  search. 

•  Error  reporting  in  Function  IIH  is  incomplete.  An  error  return  (OFFH  in  the  AL  regis¬ 
ter)  does  not  always  mean  that  the  file  does  not  exist.  Other  possibilities  include 

-  Filename  in  the  FCB  was  improperly  specified. 

-■  If  an  extended  FCB  was  used,  no  files  match  the  attributes  given. 

With  MS-DOS  versions  3.0  and  later.  Function  59H  (Get  Extended  Error  Information) 
can  be  used  to  obtain  additional  information  about  the  error. 

•  With  MS-DOS  versions  2.0  and  later.  Functions  4EH  (Find  First  File)  and  4FH  (Find 
Next  File)  should  be  used  in  preference  to  Functions  IIH  and  12H. 

Related  Functions 

12H  (Find  Next  File) 
lAH  (Set  DTA  Address) 

4EH  (Find  First  File) 

4FH  (Find  Next  File) 

Example 


;  Function  IIH:  Find  First  File,  FCB-based 

/ 

;  int  FCB_first (puXFCB, attrib) 

;  char  *puXFCB; 

;  char  attrib; 

;  Returns  0  if  match  found,  otherwise  returns  -1 . 

;  Note:  The  FCB  must  have  the  drive  and 

;  filename  fields  (bytes  07H  through  12H)  and 

;  the  extension  flag  (byte  OOH)  set  before 

;  the  call  to  FCB_first  (see  Function  29H) . 

•**:^:ii***:^*****************:¥*****************4i*^¥**************^ 


(more) 
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cProc 

parmDP 

parmB 

cBegin 


cEnd 


FCB_first, PUBLIC, ds 

puXFCB 

attrib 


loadDP 

mov 

mov 

mov 

mov 

mov 

int 

cbw 


ds,dx,puXFCB  ;  Pointer  to  unopened  extended  FCB. 
bx,dx  ;  BX  points  at  FCB,  too. 

al, attrib  ;  Get  search  attribute. 

[bx+6],al  ;  Put  attribute  into  extended  FCB 

;  area . 

byte  ptr  [bx],0ffh  ;  Set  flag  for  extended  FCB. 


ah,11h 


21h 


Ask  MS-DOS  to  find  1st  matching 
file  in  current  directory. 

If  match  found,  directory  entry  can 
be  found  at  DTA  address . 

Set  return  value  to  0  or  -1  . 
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IntelTlipt  21H  C33)  l.O  and  later 

Function  12H  (18) 

Find  Next  File 


Function  12H  searches  the  current  directory  for  the  next  file  that  matches  a  specified 

filename  and  extension.  The  function  assumes  a  previous  successful  call  to  Function  IIH 

(Find  First  File)  with  the  same  file  control  block  (FCB). 

To  Call 

AH  =  12H 

DS:DX  =  segment:offset  of  search  FCB 

Returns 

If  function  is  successful: 

AL  =  OOH 

Disk  transfer  area  (DTA)  contains  unopened  FCB  of  same  type  (normal  or  extended)  as 

search  FCB. 

If  function  is  not  successful: 

AL  =  FFH 

Programmer’s  Notes 

•  Function  12H  assumes  that  a  successful  call  to  Function  llH'(Find  First  File)  has  been 
completed  with  the  same  FCB.  The  FCB  specifies  the  search  pattern.  This  function 
also  assumes  that  the  wildcard  character  ?  appears  at  least  once  in  the  filename  or 
extension  specified. 

•  An  error  (indicated  by  OFFH  returned  in  register  AL)  does  not  necessarily  mean  that 
a  file  matching  the  file  specification  does  not  exist  in  the  current  directory.  MS-DOS 
relies  on  certain  information  that  appears  in  the  search  FCB  initialized  by  Function 
IIH,  so  it  is  important  not  to  alter  that  FCB  either  between  calls  to  Functions  IIH  and 
12H  or  between  subsequent  calls  to  Function  12H. 

•  If  drive  code  0  (the  default  drive)  was  used  in  the  call  to  Function  IIH,  MS-DOS  has 
already  filled  in  the  actual  drive  number  for  the  current  directory.  MS-DOS  continues 
to  use  that  drive  for  all  calls  to  Function  12H  that  use  the  same  FCB,  regardless  of  the 
default  drive  in  effect  at  the  time  of  the  call. 

•  With  MS-DOS  versions  2.0  and  later,  Functions  4EH  (Find  First  File)  and  4FH  (Find 
Next  File)  should  be  used  in  preference  to  Functions  IIH  and  12H. 
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Related  Functions 

IIH  (Find  First  File) 
lAH  (Set  DTA  Address) 
4EH  (Find  First  File) 
4FH  (Find  Next  File) 

Example 


;******!|!*****J|e******************************S|t****************^ 

;  Function  12H:  Find  Next  File,  FCB-based 

;  int  FCB_next (puXFCB) 

;  char  *puXFCB; 

;  Returns  0  if  match  found,  otherwise  returns  -1 . 

;  Note:  The  FCB  must  have  the  drive  and 

;  filename  fields  (bytes  07H  through  12H)  and 

;  the  extension  flag  (byte  OOH)  set  before 

;  the  call  to  FCB_next  (see  Function  29H) . 

t 

cProc  FCB_next, PUBLIC,  ds 

parmDP  puXFCB 

cBegin 


loadDP 

ds,dx, puXFCB 

;  Pointer  to  unopened  extended  FCB. 

mov 

ah, 12h 

;  Ask  MS-DOS  to  find  next  matching 
;  file  in  current  directory. 

int 

21h 

;  If  match  found,  directory  entry  can 
;  be  found  at  DTA  address. 

cbw 

;  Set  return  value  to  0  or  -1  . 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  13H  (19) 

Delete  File 


Function  13H  deletes  all  files  matching  a  specified  name  and  extension  from  the  current 
directory. 

ToCaU 

AH  =  13H 

DS:DX  =  segment:offset  of  an  unopened  file  control  block  (FCB) 

Returns 

If  function  is  successful: 

AL  =  OOH 

If  function  is  not  successful: 

AL  =  FFH 

Programmer’s  Notes 

•  The  wildcard  character  ?  can  be  used  to  match  any  character  or  sequence  of  charac¬ 
ters  in  specifying  the  filename  and  extension. 

•  Open  files  must  not  be  deleted. 

•  Function  13H  does  not  support  pathnames. 

•  An  error  (indicated  by  OFFH  returned  in  register  AL)  does  not  necessarily  mean  that 
the  filename  specified  does  not  exist  in  the  current  directory.  Other  possible  causes 
for  an  error  include 

-  Filename  in  the  FCB  is  improperly  specified. 

-  File  is  a  read-only,  hidden,  or  system  file  and  an  extended  FCB  with  the  appropri¬ 
ate  attribute  byte  was  not  used. 

-  Program  attempted  to  delete  a  volume  label  and  the  label  does  not  exist  or  a  prop¬ 
erly  formatted  extended  FCB  was  not  used. 

-  In  networking  environments,  file  is  locked  or  access  rights  are  insufficient  for 
deletion. 

•  MS-DOS  removes  file  allocation  table  (FAT)  mapping  for  the  file  or  files  deleted  by 
this  function  and  flushes  the  FAT  to  disk  to  ensure  that  the  disk  contains  a  correct 
table.  The  first  character  of  the  filename  in  the  directory  entry  is  replaced  by  the  value 
0E5H,  indicating  a  deleted  file. 

•  Because  the  function  does  not  physically  erase  data,  use  of  Function  13H  alone  is  not 
sufficient  in  security-critical  applications  that  strictly  prohibit  viewing  the  data. 
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•  On  networks  running  under  MS-DOS  versions  3.1  and  later,  the  user  must  have  Create 
access  rights  to  the  directory  containing  the  file  to  be  deleted. 

•  Because  Function  13H  deletes  all  files  matching  a  given  file  specification,  a  conser¬ 
vative  approach  is  to  use  a  combination  of  Functions  IIH  (Find  First  File)  and  12H 
(Find  Next  File)  to  build  a  list  of  files  matching  the  file  specification  and  then  obtain 
confirmation  from  the  user  before  deleting  the  files  in  the  list. 

•  With  MS-DOS  versions  2.0  and  later.  Function  41H  (Delete  File)  should  be  used  in 
preference  to  Function  13H. 

Related  Function 

41H  (Delete  File) 

Example 


;  Function  13H:  Delete  File(s),  FCB-based 

;  int  FCB_delete (uXFCB) 

;  char  ♦uXFCB; 

;  Returns  0  if  file(s)  were  deleted  OK,  otherwise 

;  returns  -1 . 

;  Note:  uXFCB  must  have  the  drive  and 

;  filename  fields  (bytes  07H  through  12H)  and 

;  the  extension  flag  (byte  OOH)  set  before 

;  the  call  to  FCB_delete  (see  Function  29H) . 

cProc  FCB_delete, PUBLIC, ds 
parmDP  puXFCB 
cBegin 

loadDP  ds,dx,puXFCB 
mov  ah, 1 3h 

int  21 h 

cbw 


;  Pointer  to  unopened  extended  FCB. 
;  Ask  MS-DOS  to  delete  file(s). 

;  Return  value  of  0  or  -1  . 
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Interrupt  21H  (33)  1.0  and  later 

Function  14H  (20) 

Sequential  Read 


Function  14H  reads  the  next  sequential  block  of  data  from  a  file  and  places  the  data  in  the 
current  disk  transfer  area  (DTA). 

ToCaU 


AH  =  14H 

DS:DX  =  segmentioffset  of  a  previously  opened  file  control  block  (FCB) 

Returns 


AL  =  OOH 

OlH 
02H 
03H 

IfAL  =  00Hor03H: 


read  successful 

end  of  file  encountered;  no  data  in  record 

DTA  too  small  (segment  wrap  error);  read  canceled 

end  of  file;  partial  record  read 


DTA  contains  data  read  from  file. 


Programmer's  Notes 

•  If  necessary,  Function  lAH  (Set  DTA  Address)  should  be  used  to  set  the  base  address 
of  the  DTA  before  Function  14H  is  called.  The  default  DTA  is  128  bytes  and  is  located 
at  offset  80H  of  the  program  segment  prefix  (PSP).  If  record  sizes  larger  than  128  bytes 
will  be  used,  the  program  must  change  the  DTA  address  to  point  to  a  buffer  of  ade¬ 
quate  size. 

•  The  read  process  begins  at  the  current  position  in  the  file.  When  the  read  is  complete. 
Function  14H  increments  the  current-block  and  current-record  fields  of  the  FCB. 

•  The  size  of  the  record  loaded  into  the  DTA  is  specified  in  the  record  size  field  of  the 
FCB.  The  default  is  128  bytes,  set  by  Function  OFH  (Open  File  with  FCB)  or  Function 
16H  (Create  File  with  FCB).  If  the  record  size  is  not  128  bytes,  the  application  must  set 
the  record  size  correctly  before  issuing  any  reads. 

•  Function  OFH  does  not  fill  in  the  current-record  field  of  the  FCB  when  opening  a  file, 
so  this  field  must  be  explicitly  set  (usually  to  zero)  before  the  first  call  to  Function 
14H.  The  record  pointer,  which  includes  the  current-block  and  current-record  fields  of 
the  FCB,  is  incremented  when  Function  14H  is  successfully  completed. 

•  Function  14H  deals  with  fixed-length  records  only.  Buffering  logic  must  be  added  to 
an  application  if  variable-length  records  are  to  be  manipulated. 

•  The  block  of  data  to  be  read  can  be  chosen  by  changing  the  current-block  and 
current-record  fields  of  the  FCB. 
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•  Partial  records  read  at  the  end  of  a  file  are  padded  with  zeros  to  the  requested  record 
length. 

•  On  networks  running  under  MS-DOS  version  3.1  or  later,  the  user  must  have  Read 
access  rights  to  the  directory  containing  the  file  to  be  read. 

•  With  MS-DOS  versions  2.0  and  later,  Function  3FH  (Read  File  or  Device)  should  be 
used  in  preference  to  Function  14H. 

Related  Functions 


15H  (Sequential  Write) 
lAH  (Set  DTA  Address) 
21H  (Random  Read) 

27H  (Random  Block  Read) 
3FH  (Read  File  or  Device) 

Example 


Function  14H:  Sequential  Read,  FCB-based 

int  FCB_sread(oXFCB) 
char  *oXFCB; 

Returns  0  if  record  read  OK,  otherwise 
returns  error  code  1,  2,  or  3. 


cProc 

FCB_sread, PUBLIC, ds 

parmDP 

poXFCB 

cBegin 

loadDP 

ds, dx,poXFCB 

;  Pointer  to 

opened  extended 

FCB. 

mov 

ah,14h 

;  Ask  MS-DOS 

to  read  next  record. 

;  placing  it 

at  DTA. 

int 

21h 

cbw 

;  Clear  high  byte  for  return 

value 

cEnd 


1230  The  MS-DOS  Encyclopedia 


Interrupt  21H  Function  15H 


Interrupt  21H  (33)  1.0  and  later 

Function  15H  (21) 

Sequential  Write 


Function  15H  writes  the  next  sequential  block  of  data  from  the  disk  transfer  area  (DTA)  to 

a  specified  file. 

ToCaU 

AH  =  15H 

DS:DX  =  segment:offset  of  a  previously  opened  file  control  block  (FCB) 

DTA  contains  data  to  write. 

Returns 

AL  =  OOH  block  written  successfully 

OlH  disk  full;  write  canceled 

02H  DTA  too  small  (segment  wrap  error);  write  canceled 

Programmer’s  Notes 

•  If  necessary,  the  calling  process  should  set  the  DTA  address  with  Function  lAH  (Set 
DTA  Address)  to  point  to  the  data  to  be  written  before  issuing  a  call  to  Function  15H. 
The  default  address  of  the  DTA  is  offset  80H  in  the  program  segment  prefix  (PSP). 

•  The  FCB  must  already  have  been  filled  in  by  a  call  to  Function  OFH  (Open  File  with 
FCB)  before  Function  15H  is  called. 

•  The  location  of  the  block  to  be  written  is  given  by  the  current-block  and  current- 
record  fields  of  the  FCB.  If  the  write  is  successful,  Function  15H  increments  the 
current-block  and  current-record  fields. 

•  The  size  of  the  record  written  by  Function  15H  is  determined  by  the  value  in  the 
record  size  field  of  the  FCB.  The  default  value  is  128,  set  by  Function  OFH  (Open  File 
with  FCB)  or  Function  16H  (Create  File  with  FCB).  A  process  must  set  the  record  size 
in  the  FCB  correctly  before  issuing  any  writes. 

•  Function  15H  deals  with  fixed-length  records  only.  Buffering  logic  must  be  added  to 
an  application  if  variable-length  records  are  to  be  manipulated. 

•  Function  15H  performs  a  logical,  but  not  necessarily  physical,  write  operation.  If  less 
than  one  sector  is  being  written,  MS-DOS  moves  the  record  from  the  DTA  to  an  appro¬ 
priate  MS-DOS  internal  buffer.  When  a  full  sector  of  data  has  been  buffered,  MS-DOS 
flushes  the  buffer  to  disk.  Function  ODH  (Disk  Reset)  or  Function  lOH  (Close  File  with 
FCB)  can  be  used  to  flush  data  to  disk  before  a  full  sector  is  buffered. 

•  On  networks  running  under  MS-DOS  versions  3.1  and  later,  the  user  must  have  Write 
access  to  the  directory  containing  the  file  to  be  written  to. 

•  With  MS-DOS  versions  2.0  and  later.  Function  40H  (Write  File  or  Device)  should  be 
used  in  preference  to  Function  15H. 
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Related  Functions 

14H  (Sequential  Read) 
lAH  (Set  DTA  Address) 
22H  (Random  Write) 

28H  (Random  Block  Write) 
40H  (Write  File  or  Device) 

Example 


Function  15H:  Sequential  Write,  FCB-based 

int  FCB_swrite (oXFCB) 
char  *oXFCB; 

Returns  0  if  record  read  OK,  otherwise 
returns  error  code  1  or  2 . 


cProc 

FCB_swrite, PUBLIC, ds 

parmDP 

poXFCB 

cBegin 

loadDP 

ds, dx,poXFCB 

;  Pointer  to  opened  extended  FCB. 

mov 

ah, 15h 

;  Ask  MS-DOS  to  write  next  record 

;  from  DTA  to  disk  file. 

int 

21h 

cbw 

;  Clear  high  byte  for  return  value 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  16H  (22) 

Create  File  with  FCB 


Function  16H  creates  a  directory  entry  in  the  current  directory  for  a  specified  file  and 
opens  the  file  for  use.  If  the  file  already  exists,  it  is  opened  and  truncated  to  zero  length. 

ToCaU 

AH  =  16H 

DS:DX  =  segmentroffset  of  an  unopened  file  control  block  (FCB) 

Returns 

If  function  is  successful: 

AL  =  OOH 

If  function  is  not  successful: 

AL  =  FFH 

Programmer’s  Notes 

•  Before  creating  a  new  directory  entry  for  the  specified  file,  Function  16H  searches 
the  current  directory  for  a  matching  filename.  If  a  match  is  found,  the  existing  file  is 
opened,  but  its  length  is  set  to  0.  In  effect,  this  action  erases  an  existing  file  and 
replaces  it  with  a  new,  empty  file  of  the  same  name. 

If  a  matching  filename  is  not  found  and  the  directory  has  room  for  a  new  entry,  the 
file  is  created  and  opened,  and  its  length  is  set  to  0. 

•  An  extended  file  control  block  (FCB)  can  be  used  to  create  a  file  with  a  special 
attribute,  such  as  hidden.  Before  the  Create  File  call  is  issued,  the  attribute  byte  must 
be  set  appropriately. 

•  A  value  of  OFFH  returned  in  the  AL  register  can  indicate  one  of  several  errors: 

-  Filename  was  improperly  specified  in  the  FCB. 

-  File  with  the  same  name  exists  but  is  a  read-only,  hidden,  system,  or  (in  MS-DOS 
versions  3.x  and  networks)  locked  file. 

-  Disk  is  full. 

-  Current  working  directory  is  the  root  directory,  and  it  is  full. 

-  User  does  not  have  the  appropriate  access  rights  to  create  a  file  in  this  directory 
(in  MS-DOS  versions  3.x  and  networks). 

With  MS-DOS  versions  3.0  and  later.  Function  59H  (Get  Extended  Error  Information) 
can  be  used  to  obtain  additional  information  about  an  error. 

•  Upon  successful  completion  of  Function  16H,  MS-DOS  has 

-  Created  and  opened  the  file  specified  in  the  FCB. 
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-  Filled  in  the  date  and  time  fields  of  the  FCB  with  the  current  date  and  time. 

-  Set  file  size  to  zero. 

All  other  changes  made  to  the  FCB  are  similar  to  those  made  by  Function  OFH  (Open 
File  with  FCB). 

•  Pathnames  and  wildcard  characters  (?  and  ♦)  are  not  supported  by  Function  16H. 

•  With  MS-DOS  versions  2.0  and  later,  Function  16H  has  been  superseded  by  Functions 
3CH  (Create  File  with  Handle),  5AH  (Create  Temporary  File),  and  5BH  (Create  New 
File). 

Related  Functions 

OFH  (Open  File  with  FCB) 

3CH  (Create  File  with  Handle) 

3DH  (Open  File  with  Handle) 

5AH  (Create  Temporary  File) 

5BH  (Create  New  File) 

Example 

;  Function  16H:  Create  File,  FCB-based  ; 

;  int  FCB_create (uXFCB, recsize)  ; 

;  char  *uXFCB; 

;  int  recsize;  ; 

;  Returns  0  if  file  created  OK,  otherwise  ; 

;  returns  -1 .  ; 

;  Note:  uXFCB  must  have  the  drive  and  filename  ; 

;  fields  (bytes  07H  through  12H)  and  the  ; 

;  extension  flag  (byte  OOH)  set  before  the  ; 

;  call  to  FCB_create  (see  Function  29H) .  ; 

•  Htilf:illiilf:illiilli;tiiliilltiiiifil!iilt:itfi;tiiti********************************************J 


cProc 

FCB_create, PUBLIC,  ds 

parmDP 

puXFCB 

parmW 

recsize 

cBegin 

loadDP 

ds,dx,puXFCB 

;  Pointer  to  unopened  extended  FCB. 

mov 

ah, 1 6h 

;  Ask  MS-DOS  to  create  file. 

int 

21h 

add 

dx,  7 

;  Advance  pointer  to  start  of  regular 
;  FCB. 

mov 

bx,dx 

;  BX  =  FCB  pointer. 

mov 

dx, recsize 

;  Get  record  size  parameter. 

mov 

[bx+Oeh] ,dx 

;  Store  record  size  in  FCB. 

xor 

dx,dx 

mov 

[bx+20h] ,dl 

;  Set  current-record 

mov 

[bx+21h] ,dx 

;  and  relative-record 

mov 

[bx+23h]  ,dx 

;  fields  to  0. 

cbw 

;  Set  return  value  to  0  or  -1 . 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  17H  (23) 

Rename  File 


Function  17H  renames  one  or  more  files  in  the  current  directory. 

ToCaU 

AH  =  17H 

DS:DX  =  segment:offset  of  modified  file  control  block  (FCB)  in  the  following  nonstan¬ 
dard  format: 


Byte(s)  Contents 


OOH 

01-08H 

09-0BH 

OCH-lOH 

19H-1BH 

11CH-24H 


Drive  number 

Old  filename  (padded  with  blanks,  if  necessary) 

Old  file  extension  (padded  with  blanks,  if  necessary) 
Zeroed  out 

New  filename  (padded  with  blanks,  if  necessary) 

New  file  extension  (padded  with  blanks,  if  necessary) 
Zeroed  out 


Returns 

If  function  is  successful: 

AL  =  OOH 

If  function  is  not  successful: 

AL  =  FFH 

Programmer’s  Notes 

•  The  wildcard  character  ?  can  be  used  in  specifying  both  the  old  and  the  new  file¬ 
names,  but  its  meaning  differs  in  each  case.  A  wildcard  character  in  the  old  filename 
matches  any  single  character  or  sequence  of  characters  in  the  directory  entry.  A 
wildcard  character  in  the  new  filename,  however,  indicates  that  the  corresponding 
character  or  characters  in  the  original  filename  are  not  to  change. 

•  With  MS-DOS  versions  2.0  and  later.  Function  17H  views  subdirectory  entries  as  files. 
These  subdirectory  entries  can  be  renamed  using  this  function  and  an  extended  FCB 
with  the  appropriate  attribute  byte. 

•  A  value  of  OFFH  returned  in  the  AL  register  can  indicate  one  of  several  errors: 

-  Old  filename  is  improperly  specified  in  the  FCB. 

-  File  with  the  new  filename  already  exists  in  the  current  directory. 
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-  Old  file  is  a  read-only  file. 

-  With  MS-DOS  versions  3.1  and  later  in  a  networking  environment,  the  user  has  in¬ 
sufficient  access  rights  to  the  directory. 

With  MS-DOS  versions  3.0  and  later,  Function  59H  (Get  Extended  Error  Information) 
can  be  used  to  obtain  additional  information  about  the  cause  of  an  error. 

•  With  MS-DOS  versions  2.0  and  later.  Function  56H  (Rename  File)  should  be  used  in 
preference  to  Function  17H. 

Related  Function 

56H  (Rename  File) 

Example 

.  **♦***♦♦*********♦****♦♦*♦***♦♦***♦*************************; 

/ 

;  Function  17H:  Rename  File(s),  FCB-based  ; 

; 

;  int  FCB_rename (uXFCBold, uXFCBnew)  ; 

;  char  *uXFCBold, *uXFCBnew;  ; 

!  r 

;  Returns  0  if  file(s)  renamed  OK,  otherwise  ; 

;  returns  -1  .  ; 

;  / 

;  Note:  Both  uXFCB's  must  have  the  drive  and  ; 

;  filename  fields  (bytes  07H  through  12H)  and  ; 

;  the  extension  flag  (byte  OOH)  set  before  ; 

;  the  call  to  FCB_rename  (see  Function  29H) .  ; 

; 


cProc 

FCB_rename, PUBLIC,  <ds,  si, 

di> 

parmDP 

puXFCBold 

parmDP 

puXFCBnew 

cBegin 

loadDP 

es , di , puXFCBold 

ES:DI  =  Pointer  to  uXFCBold. 

mov 

dx,  di 

Save  offset  in  DX. 

add 

di,7 

Advance  pointer  to  start  of  regular 
FCBold. 

loadDP 

ds , si , puXFCBnew 

DS:SI  =  Pointer  to  uXFCBnew. 

add 

si,  8 

Advance  pointer  to  filename  field 
FCBnew . 

Copy  name  from  FCBnew  into  FCBold 
at  offset  11H; 

add 

di,11h 

DI  points  11H  bytes  into  old  FCB. 

mov 

cx, Obh 

Copy  OBH  bytes,  moving  new 

rep 

movsb 

name  into  old  FCB. 

push 

es 

Set  DS  to  segment  of  FCBold. 

pop 

ds 

mov 

ah,17h 

;  Ask  MS-DOS  to  rename  old 

int 

21h 

;  file(s)  to  new  name(s). 

cbw 

;  Set  return  flag  to  0  or  -1  . 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  19H  (25) 

Get  Current  Disk 


Function  19H  returns  the  code  for  the  current  disk  drive. 

ToCaU 

AH  =  19H 

Returns 


AL  =  drive  code  (0  =  drive  A,  1  =  drive  B,  2  =  drive  C,  and  so  on) 

Programmer’s  Note 

•  The  drive  code  returned  by  Function  19H  is  zero-based,  meaning  that  drive  A  =  0, 
drive  B  =  1,  and  so  on.  This  value  is  unlike  the  drive  code  used  in  file  control  blocks 
(FCBs)  and  in  some  other  MS-DOS  functions,  such  as  ICH  (Get  Drive  Data)  and  36H 
(Get  Disk  Free  Space),  in  which  0  indicates  the  default  rather  than  the  current  drive. 

Related  Function 

OEH  (Select  Disk) 

Example 

;*****!k*!j:5N**********45***5t:s|!*!|e*5|!*3k**H5*S|!S|!Sf!*3l!4!5j:*****!jeS|SSl£5l!s|5*sN**>it**** 

;  Function  19H:  Get  Current  Disk  ; 

;  int  cur_drive()  ; 

;  Returns  letter  of  current  "logged”  disk.  ; 

■  4c*****:l«*Hc*4!**«**H«*******3ic*H!******4e*****4:4:*******4:4:H:4c*3H******* 


cProc  cur_drive, PUBLIC 
cBegin 

mov  ah, 1 9h 

int  21 h 

add  al,  'A' 

cbw 

cEnd 


;  Set  function  code. 

;  Get  number  of  logged  disk. 

;  Convert  number  to  letter. 

;  Clear  the  high  byte  of  return  value. 
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Interrupt  21H  (33)  1.0  and  later 

Function  lAH  (26) 

Set  DTA  Address 


Function  lAH  specifies  the  location  of  the  disk  transfer  area  (DTA)  to  be  used  for  file  con¬ 
trol  block  (FCB)  disk  I/O  operations. 

ToCaU 

AH  =  lAH 

DS:DX  =  segmentioffset  of  DTA 

Returns 

Nothing 

Programmer’s  Notes 

•  If  an  application  does  not  specify  a  disk  transfer  area,  MS-DOS  uses  a  default  buffer  at 
offset  80H  in  the  program  segment  prefix  (PSP). 

•  The  DTA  specified  must  be  large  enough  to  accommodate  the  amount  of  data  to  be 
transferred  in  a  single  block.  The  default  record  size  for  FCB  file  operations  is  128 
bytes;  this  value  can  be  changed  after  a  file  is  successfully  opened  or  created  by  alter¬ 
ing  the  record  size  field  in  the  FCB.  If  the  DTA  is  too  small  for  the  record  size  used  by 
the  program,  other  code  or  data  may  be  damaged. 

•  The  location  of  the  DTA  must  be  far  enough  from  the  top  of  the  segment  that  contains 
it  to  avoid  errors  caused  by  segment  wrap  (data  wrapping  from  the  end  of  the  segment 
to  the  beginning),  which  will  cause  the  disk  transfer  to  be  terminated.  Thus,  for  exam¬ 
ple,  if  records  of  128  bytes  are  to  be  read,  the  highest  location  acceptable  for  the  DTA 
is  DS:FF80H. 

•  The  DTA  is  used  by  all  FCB-based  read  and  write  functions.  In  addition,  any  applica¬ 
tion  using  the  following  functions  must  also  set  up  a  DTA  for  use  as  a  scratch  area  in 
directory  searches: 

-  IIH  (Find  First  File) 

-  12H  (Find  Next  File) 

-  4EH  (Find  First  File) 

-  4FH  (Find  Next  File) 

Related  Function 

2FH  (Get  DTA  Address) 
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cProc  set_DTA, PUBLIC, ds 
parmD  pDTAbuffer 
cBegin 

Ids  dx, pDTAbuffer 

mov  ah,1ah 

int  21 h 

xor  ax, ax 

cEnd 


;  DS:DX  =  pointer  to  buffer. 

;  Set  function  code. 

;  Ask  MS-DOS  to  change  DTA  address. 
;  Return  0 . 
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Interrupt  21H  (33)  1.0  and  later 

Function  IBH  (27) 

Get  Default  Drive  Data 


Function  IBH  returns  information  about  the  disk  in  the  default  drive. 

ToCaU 

AH  =  IBH 

Returns 

If  function  is  successful: 

AL  =  number  of  sectors  per  cluster  (allocation  unit) 

CK  =  number  of  bytes  per  sector 

DX  =  number  of  clusters 

DS:BX  =  segment:offset  of  the  file  allocation  table  (FAT)  identification  byte 
If  function  is  not  successful: 

AL  =  FFH 

Programmer’s  Notes 

•  If  Function  IBH  returns  OFFH  in  the  AL  register,  the  current  drive  was  invalid  or  a  disk 
error  occurred.  The  most  likely  causes  of  the  latter  are 

-  Drive  door  was  open. 

-  Disk  was  not  ready. 

“  Medium  was  bad. 

-  Disk  was  unformatted. 

If  any  of  these  situations  arises,  MS-DOS  issues  Interrupt  24H  (critical  error).  If  Inter¬ 
rupt  24H  has  not  been  revectored  to  a  critical  error  handler  controlled  by  the  program 
and  the  user  responds  Ignore  to  the  MS-DOS  Abort,  Retry,  Ignore?  message,  the  error 
code  OFFH  is  returned  to  the  program.  An  application  should  check  the  AL  register 
for  a  value  of  OFFH  before  assuming  it  has  information  on  the  default  drive. 

•  Possible  values  of  the  FAT  ID  byte  (for  IBM-compatible  media)  are  the  following: 

Value  Medium 

OFFH  Double-sided,  8  sectors/track,  40  tracks/side 

OFEH  Single-sided,  8  sectors/track,  40  tracks/side 

OFDH  Double-sided,  9  sectors/track,  40  tracks/side 

OFCH  Single-sided,  9  sectors/track,  40  tracks/side 

(more) 
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Value  Medium 

0F9H  Double-sided,  15  sectors/track,  40  tracks/side  or  double-sided,  9  sectors/ 

track,  80  tracks/side 
0F8H  Fixed  disk 

OFOH  Others 

•  With  MS-DOS  versions  1.x,  Function  IBH  returns  a  pointer  in  DS:BX  for  the  actual 
memory  image  of  the  FAT.  In  MS-DOS  versions  2.0  and  later,  the  function  returns  a 
pointer  in  DS:BX  for  a  copy  of  the  FAT  identification  byte;  the  contents  of  memory 
beyond  the  identification  byte  are  not  necessarily  the  FAT  memory  image.  If  access 
to  the  FAT  is  necessary.  Interrupt  25H  (Absolute  Disk  Read)  can  be  used  to  read  it 
into  memory. 

•  The  FAT  ID  byte  is  not  enough  to  identify  a  drive  completely  in  MS-DOS  versions  2.0 
and  later.  In  these  versions  of  MS-DOS,  Function  36H  (Get  Disk  Free  Space)  should  be 
used  in  preference  to  Function  IBH  to  avoid  the  ambiguity  caused  by  the  FAT  iden¬ 
tification  byte. 

•  With  MS-DOS  versions  3.2  and  later,  additional  drive  information  can  be  obtained  by 
inspecting  the  BIOS  parameter  block  (BPB)  obtained  with  Function  44H  (lOCTL) 
Subfunction  ODH  (Generic  I/O  Control  for  Block  Devices)  minor  code  60H  (Get 
Device  Parameters). 

•  With  MS-DOS  versions  2.0  and  later.  Function  ICH  (Get  Drive  Data)  provides  the  same 
types  of  information  as  Function  IBH,  but  for  a  disk  in  a  drive  other  than  the  default 
drive. 

Related  Functions 

ICH  (Get  Drive  Data) 

36H  (Get  Disk  Free  Space) 

44H  (lOCTL) 

Example 

See  SYSTEM  CALLS:  Interrupt  21h:  Function  ICH. 
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Interrupt  21H  (33)  2.0  and  later 

Function  ICH  (28) 

Get  Drive  Data 

Function  ICH  returns  information  about  the  disk  in  a  specified  drive. 

ToCaU 

AH  =  ICH 

DL  =  drive  code  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B, 

3  =  drive  C,  and  so  on) 

Returns 

If  function  is  successful: 

AL  =  number  of  sectors  per  cluster  (allocation  unit) 

CX  =  number  of  bytes  per  sector 

DX  =  number  of  clusters 

DS:BX  =  segment:offset  of  the  file  allocation  table  (FAT)  identification  byte 

If  function  is  not  successful: 

AL  =  FFH 

Programmer’s  Notes 

•  Function  ICH  is  not  available  with  MS-DOS  versions  1.x. 

•  If  the  function  returns  OFFH  in  the  AL  register,  the  drive  code  was  invalid  or  a  disk 
error  occurred.  The  most  likely  causes  of  the  latter  are 

-  Drive  door  was  open. 

-  Disk  was  not  ready. 

-  Medium  was  bad. 

-  Disk  was  unformatted. 

If  any  of  these  situations  arises,  MS-DOS  issues  Interrupt  24H  (critical  error).  If  Inter¬ 
rupt  24H  has  not  been  revectored  to  a  critical  error  handler  controlled  by  the  program 
and  the  user  responds  Ignore  to  the  MS-DOS  Abort,  Retry,  Ignore?  message,  the  error 
code  OFFH  is  returned  to  the  program.  An  application  should  check  the  AL  register 
for  a  value  of  OFFH  before  assuming  it  has  information  on  the  specified  drive. 

•  Possible  values  of  the  FAT  ID  byte  (for  IBM-compatible  media)  are  the  following: 

Value  Medium 

OFFH  Double-sided,  8  sectors/track,  40  tracks/side 

OFEH  Single-sided,  8  sectors/track,  40  tracks/side 

(more) 
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Value  Medium 

OFDH  Double-sided,  9  sectors/track,  40  tracks/side 
OFCH  Single-sided,  9  sectors/track,  40  tracks/side 

0F9H  Double-sided,  15  sectors/track,  40  tracks/side  or  double-sided,  9  sectors/ 

track,  80  tracks/side 
0F8H  Fixed  disk 

OFOH  Others 

•  The  contents  of  memory  beyond  the  identification  byte  pointed  to  by  DS:BX  are  not 
necessarily  the  FAT  memory  image.  If  access  to  the  FAT  is  necessary.  Interrupt  25H 
(Absolute  Disk  Read)  can  be  used  to  read  it  into  memory. 

•  The  FAT  ID  byte  is  not  enough  to  identify  a  drive  completely.  To  avoid  the  ambiguity 
caused  by  the  FAT  identification  byte.  Function  36H  (Get  Disk  Free  Space)  should  be 
used  in  preference  to  Function  ICH. 

•  With  MS-DOS  versions  3.2  and  later,  additional  drive  information  can  be  obtained  by 
inspecting  the  BIOS  parameter  block  (BPB)  obtained  with  Function  44H  (lOCTL) 
Subfunction  ODH  (Generic  I/O  Control  for  Block  Devices)  minor  code  60H  (Get 
Device  Parameters). 

Related  Functions 

IBH  (Get  Default  Drive  Data) 

36H  (Get  Disk  Free  Space) 

44H(IOCTL) 

Example 


Function  ICH:  Get  Drive  Data 

Get  information  about  the  disk  in  the  specified 

drive.  Set  drive_ltr  to  binary  0  for  default  drive  info. 

int  get_drive_data (drive_ltr, 
pbytes_per_sector, 
psectors_per_cluster, 
pclusters_per_drive) 
int  drive_ltr; 
int  *pbytes_per_sector; 
int  *psectors_per_cluster; 
int  *pclusters_per_drive; 

Returns  -1  for  invalid  drive,  otherwise  returns 
the  disk's  type  (from  the  1st  byte  of  the  FAT). 


(more) 
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cProc  get_drive_data, PUBLIC,  <ds,  si> 

parmB  drive_ltr 

parmDP  pbytes_per_sector 

parmDP  psectors_per_cluster 

parmDP  pclusters_per_drive 

cBegin 


mov 

si,  ds 

/  Save  DS  in  SI  to  use  later. 

mov 

dl, drive_ltr 

;  Get  drive  letter. 

or 

dl,dl 

;  Leave  0  alone. 

jz 

gdd 

and 

dl,not  20h 

;  Convert  letter  to  uppercase. 

sub 

dl, ’A'-1 

;  Convert  to  drive  number:  'A' 

;  'B'  =  2,  etc. 

mov 

ah, 1 ch 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  for  data. 

cbw 

;  Extend  AL  into  AH. 

cmp 

al,0ffh 

;  Bad  drive  letter? 

je 

gddx 

;  If  so,  exit  with  error  code  - 

mov 

bl, [bx] 

;  Get  FAT  ID  byte  from  DS:BX. 

mov 

ds,  si 

;  Get  back  original  DS . 

loadDP 

ds,  si, pbytes_per_sector 

mov 

[si] , cx 

;  Return  bytes  per  sector. 

loadDP 

ds, si,psectors_ 

per_cluster 

mov 

ah,  0 

mov 

[si] ,ax 

;  Return  sectors  per  cluster. 

loadDP 

ds, si,pclusters 

_per_drive 

mov 

[si] , dx 

;  Return  clusters  per  drive. 

mov 

al,bl 

;  Return  FAT  ID  byte. 

gddx: 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  21H  (33) 

Random  Read 


Function  21H  reads  a  selected  record  from  disk  into  memory. 

To  Call 


AH  =  21H 

DS:DX  =  segment:offset  of  previously  opened  file  control  block  (FCB) 

Returns 


AL  =  OOH 

OlH 
02H 
03H 

IfAL  =  00Hor03H: 


record  read  successfully 
end  of  file;  no  record  read 

DTA  too  small  (segment  wrap  error);  read  canceled 
end  of  file;  partial  record  transferred 


DTA  contains  data  read  from  file. 


Programmer’s  Notes 

•  Function  21H  reads  the  record  into  the  current  disk  transfer  area  (DTA).  Unless  the 
128-byte  default  DTA  (at  offset  80H  in  the  program  segment  prefix)  is  adequate,  Func¬ 
tion  lAH  (Set  DTA  Address)  should  be  used  to  set  the  DTA  address  before  Function 
21H  is  called.  The  program  must  ensure  that  the  buffer  pointed  to  by  the  DTA  address 
is  large  enough  to  hold  the  records  to  be  transferred. 

•  The  relative-record  field  in  the  FCB  must  be  set  to  the  record  number  to  be  read.  Num¬ 
bering  begins  with  record  OOH;  thus,  the  value  06H  in  the  relative-record  field  would 
indicate  the  seventh  record,  not  the  sixth. 

•  Function  21H  sets  the  current-block  and  current-record  fields  to  match  the  relative- 
record  field  before  transferring  the  data  to  the  DTA. 

•  Unlike  Function  27H  (Random  Block  Read),  Function  21H  does  not  increment  the 
current-block,  current-record,  or  relative-record  fields. 

•  The  record  length  read  is  determined  by  the  record  size  field  of  the  FCB. 

•  If  a  partial  record  is  read  and  the  end  of  file  is  encountered,  the  remainder  of  the 
record  is  filled  out  to  the  requested  length  with  zero  bytes. 

•  On  networks  running  under  MS-DOS  version  3.1  or  later,  the  user  must  have  Read 
access  rights  to  the  directory  containing  the  file  to  be  read. 

•  With  MS-DOS  versions  2.0  and  later.  Function  3FH  (Read  File  or  Device)  should  be 
used  in  preference  to  Function  21H. 
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Related  Functions 

14H  (Sequential  Read) 
lAH  (Set  DTA  Address) 

22H  (Random  Write) 

24H  (Set  Relative  Record) 

27H  (Random  Block  Read) 

3FH  (Read  File  or  Device) 

Example 

/ 

;  Function  21 H:  Random  File  Read,  FCB-based 

9 

;  int  FCB_rread(oXFCB, recnum) 

;  char  *oXFCB; 

;  long  recnum; 

;  Returns  0  if  record  read  OK,  otherwise 

;  returns  error  code  1,  2,  or  3 . 

9 

cProc  FCB_rread, PUBLIC, ds 

parmDP  poXFCB 

parmD  recnum 

cBegin 

loadDP  ds,dx,poXFCB  ;  Pointer  to  opened  extended  FCB. 

mov  t>x,dx  ;  BX  points  at  FCB,  too. 

mov  ax, word  ptr  (recnum)  ;  Get  low  16  bits  of  record 

mov  [bx+28h],ax  ;  number  and  store  in  FCB. 

mov  ax, word  ptr  (recnum+2)  ;  Get  high  16  bits  of  record 

mov  [bx+2ah],ax  ;  number  and  store  in  FCB. 

mov  ah,21h  ;  Ask  MS-DOS  to  read  recnum' th 

;  record,  placing  it  at  DTA. 

int  21 h 

cbw  ;  Clear  high  byte  of  return  value. 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  22H  (34) 

Random  Write 


Function  22H  writes  data  from  the  current  disk  transfer  area  (DTA)  to  a  specified  record 
location  in  a  file. 

ToCaU 

AH  =  22H 

DS:DX  =  segmentioffset  of  previously  opened  file  control  block  (FCB) 

DTA  contains  data  to  write. 

Returns 

AL  =  OOH  record  written  successfully 

OlH  disk  full 

02H  DTA  too  small  (segment  wrap  error);  write  canceled 

Programmer's  Notes 

•  Before  calling  Function  22H,  the  program  must  set  the  disk  transfer  area  (DTA)  ad¬ 
dress  appropriately  with  a  call  to  Function  lAH  (Set  DTA  Address),  if  necessary,  and 
place  the  data  to  be  written  in  the  DTA. 

•  The  relative-record  field  in  the  FCB  must  be  set  to  the  record  number  that  is  to  be  writ¬ 
ten.  Numbering  begins  with  record  OOH;  thus,  the  value  06H  in  the  relative-record 
field  would  indicate  the  seventh  record,  not  the  sixth. 

•  Function  22H  sets  the  current-block  and  current-record  fields  to  match  the  relative- 
record  field  before  writing  the  data  from  the  DTA. 

•  Unlike  Function  28H  (Random  Block  Write),  Function  22H  does  not  increment  the 
current-block,  current-record,  or  relative-record  fields. 

•  The  record  size  field  determines  the  record  length  written  by  the  function. 

•  If  a  record  is  written  beyond  the  current  end  of  file,  the  data  between  the  old  end  of 
file  and  the  beginning  of  the  new  record  is  uninitialized. 

•  The  file  that  is  written  to  cannot  have  the  read-only  attribute. 

•  Information  is  written  logically,  but  not  always  physically,  to  disk  at  the  time  Function 
22H  is  called.  The  contents  of  the  DTA  are  written  immediately  to  disk  only  if  they 
constitute  a  sector’s  worth  of  information.  If  less  than  a  sector  is  written,  it  is  trans¬ 
ferred  from  the  DTA  to  an  MS-DOS  buffer  and  is  not  physically  written  to  disk  until 
one  of  the  following  occurs: 

-  A  full  sector  of  information  is  ready. 

-  The  file  is  closed. 

-  Function  ODH  (Disk  Reset)  is  issued. 
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•  On  networks  running  under  MS-DOS  version  3.1  or  later,  the  user  must  have  Write 
access  rights  to  the  directory  containing  the  file  to  be  written  to. 

•  With  MS-DOS  versions  2.0  and  later,  Function  40H  (Write  File  or  Device)  should  be 
used  in  preference  to  Function  22H. 

Related  Functions 

15H  (Sequential  Write) 
lAH  (Set  DTA  Address) 

21H  (Random  Read) 

24H  (Set  Relative  Record) 

28H  (Random  Block  Write) 

40H  (Write  File  or  Device) 

Example 

;  Function  22H:  Random  File  Write,  FCB-based  ; 

;  int  FCB_rwrite (oXFCB, recnum)  ; 

;  char  *oXFCB;  ; 

;  long  recnum;  ; 

;  Returns  0  if  record  read  OK,  otherwise  ; 

;  returns  error  code  1  or  2 .  ; 

cProc  FCB_rwrite, PUBLIC, ds 
parmDP  poXFCB 
parmD  recnum 
cBegin 

loadDP  ds,dx,poXFCB  ;  Pointer  to  opened  extended  FCB. 

mov  bx,dx  ;  BX  points  at  FCB,  too. 

mov  ax, word  ptr  (recnum)  ;  Get  low  16  bits  of  record 

mov  [bx+28h],ax  ;  number  and  store  in  FCB. 

mov  ax, word  ptr  (recnum+2)  ;  Get  high  16  bits  of  record 

mov  [bx+2ah],ax  ;  number  and  store  in  FCB. 

mov  ah,22h  ;  Ask  MS-DOS  to  write  DTA  to 

int  21 h  ;  recnum' th  record  of  file, 

cbw  ;  Clear  high  byte  for  return  value. 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  23H  (35) 

Get  File  Size 


Function  23H  searches  the  current  directory  for  a  specified  file  and  returns  the  size  of  the 

file  in  records. 

ToCaU 

AH  =  23H 

DS:DX  =  segment:offset  of  unopened  file  control  block  (FCB)  with  record  size  field  set 
appropriately 

Returns 

If  function  is  successful: 

AL  =  OOH 

FCB  relative-record  field  contains  number  of  records,  rounded  upward  if  necessary. 

If  function  is  not  successful: 

AL  =  FFH 

Programmer's  Notes 

•  The  record  size  field  in  the  FCB  can  be  set  to  1  to  find  the  number  of  bytes  in  the  file. 

•  The  number  of  records  is  the  file  size  divided  by  the  record  size.  If  there  is  a  remain¬ 
der,  the  record  count  is  rounded  upward.  The  result  stored  in  the  relative-record  field 
may,  therefore,  contain  a  value  that  is  1  larger  than  the  number  of  complete  records  in 
the  file. 

•  Because  record  numbers  are  zero  based  and  this  function  returns  the  number  of 
records  in  a  file  in  the  relative-record  field  of  the  FCB,  Function  23H  can  be  used  to 
position  the  file  pointer  to  the  end  of  file. 

•  With  MS-DOS  versions  2.0  and  later,  Function  42H  (Move  File  Pointer)  should  be  used 
in  preference  to  Function  23H. 

Related  Function 

42H  (Move  File  Pointer) 


Section  V:  System  Calls  1249 


Interrupt  21H  Function  23H 


Example 


**Hi4iHcHi***!iiiii************************************************* 

Function  23H:  Get  File  Size,  FCB-based 

long  FCB_nrecs (uXFCB, recsize) 
char  *uXFCB; 
int  recsize; 

Returns  a  long  -1  if  file  not  found,  otherwise 
returns  the  number  of  records  of  size  recsize. 

Note:  uXFCB  must  have  the  drive  and 
filename  fields  (bytes  07H  through  12H)  and 
the  extension  flag  (byte  OOH)  set  before 
the  call  to  FCB_nrecs  (see  Function  29H) . 

iti*itL****itt****Hi***;ti*iH*i^*:¥************************************* 


FCB_nrecs, PUBLIC, ds 

puXFCB 

recsize 


cProc 
parmDP 
parmW 
cBegin 

loadDP 

mov 

mov 

mov 

mov 

int 

cbw 

cwd 

or 

js 

mov 


mov 

mov 

nr_exit : 
cEnd 


ds, dx,puXFCB 

bx,dx 

ax, recsize 

[bx+1 5h] , ax 

ah,23h 

21h 


dx,dx 
nr_exit 
[bx+2bh] ,al 


ax, [bx+28h] 
dx, [bx+2ah] 


;  Pointer  to  unopened  extended  FCB. 

;  Copy  FCB  pointer  into  BX. 

;  Get  record  size 
;  and  store  it  in  FCB. 

;  Ask  MS-DOS  for  file  size  (in 
;  records) . 

;  If  AL  =  OFFH,  set  AX  to  -1  . 

/  Extend  to  long. 

;  Is  DX  negative? 

;  If  so,  exit  with  error  flag. 

;  Only  low  24  bits  of  the  relative- 
;  record  field  are  used,  so  clear  the 
;  top  8  bits. 

;  Return  file  length  in  DX:AX. 
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IntelTlipt  2UE1  C33)  1.0  and  later 

Function  24H  (36) 

Set  Relative  Record 


Function  24H  sets  the  relative-record  field  of  a  file  control  block  (FCB)  to  match  the  file 
position  indicated  by  the  current-block  and  current-record  fields  of  the  same  FCB. 

ToCaU 

AH  =  24H 

DS:DX  =  segment:offset  of  previously  opened  FCB 

Returns 

AL  =  OOH 

Relative-record  field  is  modified  in  FCB. 

Programmer’s  Notes 

•  The  AL  register  is  always  set  to  OOH  by  Function  24H.  Thus,  any  preexisting  informa¬ 
tion  in  the  AL  register  is  lost. 

•  Before  Function  24H  is  called,  the  program  must  open  the  FCB  with  Function  OFH 
(Open  File  with  FCB)  or  with  Function  16H  (Create  File  with  FCB). 

•  The  entire  relative-record  field  (4  bytes)  of  the  FCB  must  be  initialized  to  zeros  before 
calling  Function  24H.  If  this  is  not  done,  any  value  in  the  high-order  byte  of  the  high- 
order  word  remaining  from  previous  reads  or  writes  might  not  be  overwritten  and  the 
resulting  relative-record  number  will  be  invalid. 

•  Function  24H  is  normally  used  in  changing  from  sequential  to  random  I/O.  Sequential 
I/O,  performed  by  Functions  14H  (Sequential  Read)  and  15H  (Sequential  Write),  sets 
the  current-block  and  current-record  fields  of  the  FCB.  Random  I/O  uses  the  relative- 
record  field,  which  is  set  by  Function  24H  to  match  the  current  file  position  as 
recorded  in  the  current-block  and  current-record  fields. 

After  the  file  pointer  is  set,  any  of  the  following  functions  can  be  used  to  access  data  at 
the  record  pointed  to  by  the  relative-record  field: 

-  21H  (Random  Read) 

-  22H  (Random  Write) 

-  27H  (Random  Block  Read) 

-  28H  (Random  Block  Write) 

•  With  MS-DOS  versions  2.0  and  later.  Function  42H  (Move  File  Pointer)  should  be  used 
in  preference  to  Function  24H. 

Related  Function 

42H  (Move  File  Pointer) 
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Example 


.*********^1^^141************************************************ 

f 

;  Function  24H:  Set  Relative  Record 

;  int  FCB_set_rrec (oXFCB) 

;  char  *oXFCB; 

/ 

;  Returns  0. 

cProc  FCB_set_rrec, PUBLIC, ds 

parmDP  poXFCB 

cBegin 


loadDP 

ds,dx,poXFCB 

;  Pointer  to  opened  extended 

FCB. 

mov 

bx,  dx 

;  BX  points  at  FCB,  too. 

mov 

byte  ptr  [bx+2bh],0  ;  Zero  high  byte  of  high 

word  of 

mov 

ah, 24h 

;  relative-record  field. 

;  Ask  MS-DOS  to  set  relative 

record 

int 

xor 

21h 

ax,  ax 

;  to  current  record. 

;  Return  0 . 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  25H  (37) 

Set  Interrupt  Vector 


Function  25H  sets  an  address  in  the  interrupt  vector  table  to  point  to  a  specified  interrupt 

handler. 

ToCaU 

AH  =  25H 

AL  =  interrupt  number 

DS:DX  =  segment;offset  of  interrupt  handler 

Returns 

Nothing 

Programmer’s  Notes 

•  When  Function  25H  is  called,  the  4-byte  address  in  DS:DX  is  placed  in  the  correct 
position  in  the  interrupt  vector  table. 

•  Function  25H  is  the  recommended  method  for  initializing  or  changing  an  interrupt 
vector.  A  vector  in  the  interrupt  vector  table  should  never  be  changed  directly. 

•  Before  Function  25H  is  used  to  change  an  interrupt  vector,  the  address  of  the  current 
interrupt  handler  should  be  read  with  Function  35H  (Get  Interrupt  Vector)  and  then 
saved  for  restoration  before  the  program  terminates. 

Related  Function 

35H  (Get  Interrupt  Vector) 

Example 


Function  25H:  Set  Interrupt  Vector 

typedef  void  (far  ♦FCP) (); 
int  set—vector (intnum, vector) 
int  intnum; 

FCP  vector; 

Returns  0. 


(more) 
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cProc  set_vector, PUBLIC, ds 
parmB  intnum 
parmD  vector 
cBegin 

Ids  dx, vector 


mov 

mov 

int 

xor 

cEnd 


al, intnum 
ah,25h 
21h 
ax,  ax 


Get  vector  segment : offset  into 
DS:DX. 

Get  interrupt  number  into  AL. 
Select  "set  vector"  function. 
Ask  MS-DOS  to  change  vector. 
Return  0. 
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Interrupt  21H  (33)  1.0  and  later 

Function  26H  (38) 

Create  New  Program  Segment  Prefix 


Function  26H  creates  a  new  program  segment  prefix  (PSP)  at  a  specified  segment  address. 

ToCaU 

AH  =  26H 

DX  =  segment  address  of  the  PSP  to  create 

Returns 

Nothing 

Programmer’s  Notes 

•  Function  26H  copies  the  current  PSP  to  the  address  indicated  by  DX.  Note  that  DX 
contains  a  segment  address,  not  an  absolute  address. 

•  After  the  copy  is  made,  the  memory  size  information  located  at  offset  06H  in  the  new 
PSP  is  adjusted  to  match  the  amount  of  memory  available  to  the  new  PSP.  In  addition, 
the  current  contents  of  the  interrupt  vectors  for  Interrupt  22H  (Terminate  Routine  Ad¬ 
dress),  Interrupt  23H  (Ck)ntrol-C  Handler  Address),  and  Interrupt  24H  (Critical  Error 
Handler  Address)  are  saved  starting  at  offset  OAH  of  the  new  PSP. 

•  A  .COM  file  can  be  loaded  into  memory  immediately  after  the  new  PSP  and  execu¬ 
tion  can  begin  at  that  location.  A  .EXE  file  cannot  be  loaded  and  executed  in  this 
manner. 

•  With  MS-DOS  versions  2.0  and  later.  Function  4BH  (Load  and  Execute  Program) 
should  be  used  in  preference  to  Function  26H.  Function  4BH  can  be  used  to  load 
.COM  files,  .EXE  files,  or  overlays. 

Related  Function 

4BH  (Load  and  Execute  Program) 

Example 


Function  26H:  Create  New  Program  Segment  Prefix 

int  create_psp (pspseg) 
int  pspseg; 

Returns  0 . 


(more) 
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cProc  create_psp, PUBLIC 

parmW  pspseg 

cBegin 

mov  dx, pspseg 
mov  ah,26h 

int  21 h 

xor  ax, ax 

cEnd 


;  Get  segment  address  of  new  PSP. 
;  Set  function  code. 

;  Ask  MS-DOS  to  create  new  PSP. 

;  Return  0. 
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Interrupt  21H  (33)  1 0  and  later 

Function  27H  (39) 

Random  Block  Read 


Function  27H  reads  one  or  more  records  into  memory,  placing  the  records  in  the  current 
disk  transfer  area  (DTA). 

ToCaU 

AH  =  27H 

CX  =  number  of  records  to  read 

DS:DX  =  segment:offset  of  previously  opened  file  control  block  (FCB) 

Returns 

AL  =  OOH 

OlH 
02H 
03H 

IfALis00Hor03H: 

CX  =  number  of  records  read 

DTA  contains  data  read  from  file. 

Programmer’s  Notes 

•  The  DTA  address  should  be  set  with  Function  lAH  (Set  DTA  Address)  before  Function 
27H  is  called.  If  the  DTA  address  has  not  been  set,  MS-DOS  uses  a  default  128-byte 
DTA  at  offset  80H  in  the  program  s^ment  prefix  (PSP). 

•  Function  27H  reads  the  number  of  records  specified  in  CX  sequentially,  starting  at 
the  file  location  indicated  by  the  relative-record  and  record  size  fields  in  the  FCB.  If 
CX  =  0,  no  records  are  read. 

•  The  record  length  used  by  Function  27H  is  the  value  in  the  record  size  field  of  the 
FCB.  Unless  a  new  value  is  placed  in  this  field  after  a  file  is  opened  or  created, 
MS-DOS  uses  a  default  record  length  of  128  bytes. 

•  Function  27H  is  similar  to  Function  21H  (Random  Read);  however.  Function  27H  can 
read  more  than  one  record  at  a  time  and  updates  the  relative-record  field  of  the  FCB 
after  each  call.  Successive  calls  to  this  function  thus  read  sequential  groups  of  records 
from  a  file,  whereas  successive  calls  to  Function  21H  repeatedly  read  the  same  record. 

•  Possible  alternative  causes  for  end-of-file  (OlH)  errors  include 

-  Disk  removed  from  drive  since  file  was  opened. 

-  Previous  open  failed. 

With  MS-DOS  versions  3  0  and  later,  more  detailed  information  on  the  error  can  be 
obtained  by  calling  Function  59H  (Get  Extended  Error  Information). 


read  successful 

end  of  file;  no  record  read 

DTA  too  small  (segment  wrap  error);  no  record  read 
end  of  file;  partial  record  read 
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•  On  networks  running  under  MS-DOS  version  3.1  or  later,  the  user  must  have  Read 
access  rights  to  the  directory  containing  the  file  to  be  read. 

•  With  MS-DOS  versions  2.0  and  later,  Function  3FH  (Read  File  or  Device)  should  be 
used  in  preference  to  Function  27H. 

Related  Functions 

14H  (Sequential  Read) 
lAH  (Set  DTA  Address) 

21H  (Random  Read) 

24H  (Set  Relative  Record) 

28H  (Random  Block  Write) 

3FH  (Read  File  or  Device) 

Example 

.*♦*♦♦♦*♦**♦♦*********♦♦*♦♦**********♦*♦**♦******♦******♦♦*♦*; 

;  Function  27H:  Random  File  Block  Read,  FCB-based  ; 

;  int  FCB_rblock(oXFCB,nrequest,nactual, start)  ; 

;  char  *oXFCB;  ; 

;  int  nrequest;  ; 

;  int  *nactual;  ; 

;  long  start;  ; 

;  Returns  read  status  0,  1,  2,  or  3  and  sets  ; 

;  nactual  to  number  of  records  actually  read.  ; 

;  If  start  is  -1,  the  relative-record  field  is  ; 

;  not  changed,  causing  the  block  to  be  read  starting  ; 

;  at  the  current  record.  ; 

.♦♦♦***♦***♦**********♦*♦*♦***♦***♦*♦*******♦♦***♦♦**♦♦*♦*♦♦*; 


cProc 

FCB_rblock, PUBLIC, <ds, di> 

parmDP 

poXFCB 

parmW 

nrequest 

parmDP 

pnactual 

parmD 

start 

cBegin 

loadDP 

ds, dx, poXFCB 

;  Pointer  to  opened  extended  FCB. 

mov 

di,dx 

;  DI  points  at  FCB,  too. 

mov 

ax, word  ptr 

(start)  ;  Get  long  value  of  start. 

mov 

bx,word  ptr 

(start+2) 

mov 

cx,  ax 

;  Is  start  =  -1? 

and 

cx,bx 

inc 

cx 

jcxz 

rb_skip 

;  If  so,  don't  change  relative-record 
;  field. 

mov 

[di+28h] , ax 

;  Otherwise,  seek  to  start  record. 

(more) 
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rb_skip 


cEnd 


mov 

[di+2ah] ,bx 

mov 

cx, nrequest 

CX  =  number  of  records  to  read 

mov 

ah,27h 

Get  MS-DOS  to  read  CX  records. 

int 

21h 

placing  them  at  DTA. 

loadDP 

ds,bx,pnactual 

DS:BX  =  address  of  nactual. 

mov 

[bx] , cx 

Return  number  of  records  read. 

cbw 

Clear  high  byte. 
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Interrupt  21H  (33)  1  o  and  later 

Function  28H  (40) 

Random  Block  Write 


Function  28H  writes  one  or  more  records  from  the  current  disk  transfer  area  (DTA) 

to  a  file. 

ToCaU 

AH  =  28H 

CK  =  number  of  records  to  write 

DS:DX  =  segment:offset  of  previously  opened  file  control  block  (FCB) 

DTA  contains  data  to  write. 

Returns 

AL  =  OOH  write  successful 

OlH  disk  full 

02H  DTA  too  small  (segment  wrap  error);  write  canceled 

IfALis  OOH  or  OlH: 

CX  =  number  of  records  written 

Programmer’s  Notes 

•  Data  to  be  written  must  be  placed  in  the  DTA  before  Function  28H  is  called.  Unless 
the  DTA  address  has  been  set  with  Function  lAH  (Set  DTA  Address),  MS-DOS  uses  a 
default  128-byte  DTA  at  offset  80H  in  the  program  segment  prefix  (PSP). 

•  Function  28H  writes  the  number  of  records  indicated  in  CX,  beginning  at  the  location 
specified  in  the  relative-record  field  of  the  file  control  block  (FCB).  If  Function  28H  is 
called  with  CX  =  0,  the  file  is  truncated  or  extended  to  the  size  indicated  by  the  record- 
size  and  relative-record  fields  of  the  FCB. 

•  The  record  length  used  by  Function  28H  is  the  value  in  the  record  size  field  of  the 
FCB.  Unless  a  new  value  is  assigned  after  a  file  is  opened  or  created,  MS-DOS  uses  a 
default  record  length  of  128  bytes. 

•  Function  28H  is  similar  to  Function  22H  (Random  Write);  however.  Function  28H  can 
write  more  than  one  record  at  a  time  and  updates  the  relative-record  field  of  the  FCB 
after  each  call.  Successive  calls  to  this  function  thus  write  sequential  groups  of  records 
to  a  file,  whereas  successive  calls  to  Function  22H  repeatedly  write  the  same  record. 


1260 


The  MS-DOS  Encyclopedia 


Interrupt  21H  Function  28H 


•  Possible  alternative  causes  for  disk  full  (OlH)  errors  include 

-  Disk  removed  from  drive  since  file  was  opened. 

-  Previous  open  failed. 

In  MS-DOS  versions  3.0  and  later,  more  detailed  information  on  the  error  can  be 
obtained  by  calling  Function  59H  (Get  Extended  Error  Information). 

•  Information  is  written  logically,  but  not  always  physically,  to  disk  at  the  time  Function 
28H  is  called.  The  contents  of  the  DTA  are  written  immediately  to  disk  only  if  they 
constitute  a  full  sector  of  information.  If  less  than  a  sector  is  written,  it  is  transferred 
from  the  DTA  to  an  MS-DOS  buffer  and  is  not  physically  written  to  disk  until  one  of 
the  following  occurs: 

-  A  full  sector  of  information  is  ready. 

-  The  file  is  closed. 

-  Function  ODH  (Disk  Reset)  is  issued. 

•  On  networks  running  under  MS-DOS  version  3.1  or  later,  the  user  must  have  Write 
access  rights  to  the  directory  containing  the  file  to  be  written  to. 

•  With  MS-DOS  versions  2.0  and  later.  Function  40H  (Write  File  or  Device)  should  be 
used  in  preference  to  Function  28H. 

Related  Functions 

15H  (Sequential  Write) 
lAH  (Set  DTA  Address) 

22H  (Random  Write) 

24H  (Set  Relative  Record) 

27H  (Random  Block  Read) 

40H  (Write  File  or  Device) 

Example 


Function  28H:  Random  File  Block  Write,  FCB-based 

int  FCB_wblock (oXFCB, nrequest, nactual, start) 
char  *oXFCB; 
int  nrequest; 
int  *nactual; 
long  start; 

Returns  write  status  of  0,  1,  or  2  and  sets 
nactual  to  number  of  records  actually  written. 

If  start  is  -1,  the  relative-record  field  is 
not  changed,  causing  the  block  to  be  written 
starting  at  the  current  record. 


(more) 
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cProc 

parmDP 

parmW 

parmDP 

parmD 

cBegin 


wb_skip 


cEnd 


FCB_wblock, PUBLIC, <ds, di> 

poXFCB 

nrequest 

pnactual 

start 


loadDP 

mov 

mov 

mov 

mov 

and 

inc 

jcxz 

mov 

mov 


ds,dx,poXFCB  ;  Pointer  to  opened  extended  FCB. 

di,dx  ;  DI  points  at  FCB,  too. 

ax, word  ptr  (start)  ;  Get  long  value  of  start. 
bx,word  ptr  (start+2) 


cx,ax 

cx,bx 

cx 

wb_skip 

[di+28hl , ax 
[di+2ah] ,bx 


Is  start  =  -1? 


If  so,  don't  change  relative-record 
field. 

Otherwise,  seek  to  start  record. 


mov  cx, nrequest 

mov  ah,28h 

int  21 h 

loadDP  ds,bx, pnactual 
mov  ds:[bx],cx 

cbw 


CX  =  number  of  records  to  write. 
Get  MS-DOS  to  write  CX  records 
from  DTA  to  file. 

DS:BX  =  address  of  nactual. 

Return  number  of  records  written. 
Clear  high  byte. 
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Interrupt  21H  (33)  1.0  and  later 

Function  29H(4l) 

Parse  Filename 


Function  29H  examines  a  string  for  a  valid  filename  in  the  form  drive:filename.ext.  If 
the  string  represents  a  valid  filename,  the  function  creates  an  unopened  file  control  block 
(FCB)forit. 

ToCaU 

AH  =  29H 

AL  =  code  to  control  parsing,  as  follows  (bits  0-3  only): 


Bit  Value  Meaning 


0  0 
1 

1  0 
1 

2  0 
1 

3  0 
1 


Stop  parsing  if  file  separator  is  found. 

Ignore  leading  separators  (parse  off  white  space). 

Set  drive  number  field  in  FCB  to  0  (current  drive)  if 
string  does  not  include  a  drive  identifier. 

Set  drive  as  specified  in  the  string;  leave  unaltered  if 
string  does  not  include  a  drive  identifier. 

Set  filename  field  in  the  FCB  to  blanks  (20H)  if  string 
does  not  include  a  filename. 

Leave  filename  field  unaltered  if  string  does  not 
include  a  filename. 

Set  extension  field  in  FCB  to  blanks  (20H)  if  string 
does  not  include  a  filename  extension. 

Leave  extension  field  unaltered  if  string  does  not 
include  a  filename  extension. 


DS:SI  =  segment:offset  of  string  to  parse 

ES:DI  =  segment:offset  of  buffer  for  unopened  FCB 

Returns 

AL  =  OOH  string  does  not  contain  wildcard  characters 

OlH  string  contains  wildcard  characters 

FFH  drive  specifier  invalid 

DS:SI  =  segment:offset  of  first  byte  following  the  parsed  string 

ES:DI  =  segment:offset  of  unopened  FCB 
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Programmer’s  Notes 

•  Bits  0  through  3  of  the  byte  in  the  AL  register  control  the  way  the  text  string  is  parsed; 
bits  4  through  7  are  not  used  and  must  be  0. 

•  After  MS-DOS  parses  the  string,  DS:SI  points  to  the  first  byte  following  the  parsed 
string.  If  DS:SI  points  to  an  earlier  byte,  MS-DOS  did  not  parse  the  entire  string. 

•  If  Function  29H  encounters  the  MS-DOS  wildcard  character  •  (match  all  remaining 
characters)  in  a  filename  or  extension,  the  remaining  bytes  in  the  corresponding  FCB 
field  are  set  to  the  wildcard  character  ?  (match  one  character).  For  example,  the  string 
DOS».D*  would  be  converted  to  DOS?????  in  the  filename  field  and  D??  in  the  exten¬ 
sion  field  of  the  FCB. 

•  With  MS-DOS  versions  1.x,  the  following  characters  are  filename  separators: 

+  space  tab  / "  [  ] 

\Jlth  MS-DOS  versions  2.0  and  later,  the  following  characters  are  filename  separators: 
:.;,  =  +  Space  tab 

•  The  following  characters  are  filename  terminators: 

/"[1<>1 

All  filename  separators 
Any  control  character 

•  If  the  string  does  not  contain  a  valid  filename,  ES:DI+1  points  to  an  ASCII  blank 
character  (20H). 

•  Function  29H  cannot  parse  pathnames. 

Related  Functions 
None 
Example 


♦  ♦♦♦♦♦♦♦♦♦♦♦♦♦He********************************************* 

Function  29H:  Parse  Filename  into  FCB 


int  FCB—parse (uXFCB, name, Ctrl) 
char  *uXFCB; 
char  ♦name; 
int  Ctrl; 

Returns  -1  if  error, 

0  if  no  wildcards  found, 
1  if  wildcards  found. 


(more) 
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cProc  FCB_parse,  PUBLIC,  <cis,  si,di> 

parmDP  puXFCB 

parmDP  pname 

parmB  Ctrl 

cBegin 


loadDP 

es, di, puXFCB 

;  Pointer  to  unopened  extended  FCB. 

push 

di 

;  Save  DI . 

xor 

ax,  ax 

;  Fill  all  22  (decimal)  words  of  the 
;  extended  FCB  with  zeros . 

cld 

;  Make  sure  direction  flag  says  UP. 

mov 

cx, 22d 

rep 

stosw 

pop 

di 

;  Recover  DI . 

mov 

byte  ptr  [di], 

r  Offh  ;  Set  flag  byte  to  mark  this  as  an 
;  extended  FCB . 

add 

di,7 

;  Advance  pointer  to  start  of  regular 
;  FCB. 

loadDP 

ds, si, pname 

;  Get  pointer  to  filename  into  DS:SI. 

mov 

al, Ctrl 

;  Get  parse  control  byte. 

mov 

ah,29h 

;  Parse  filename,  please. 

int 

21h 

cbw 

/  Set  return  parameter. 

cEnd 
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Interrupt  21H  (33)  1.0  and  later 

Function  2AH  (42) 

Get  Date 


Function  2AH  returns  the  current  system  date — year,  month,  day,  and  day  of  the  week — 
in  binary  form. 

ToCaU 

AH  =2AH 

Returns 

AL  =  day  of  the  week  (0  =  Sunday,  1  =  Monday,  2  =  Tuesday,  and  so  on; 

MS-DOS  versions  1.10  and  later) 

CX  =  year  (1980  through  2099) 

DH  =  month  (1  through  12) 

DL  =  day  (1  through  31) 

Programmer’s  Note 

•  Years  outside  the  range  1980- 2099  cannot  be  returned  by  Function  2AH. 

Related  Functions 

2BH  (Set  Date) 

2CH  (Get  Time) 

2DH  (Set  Time) 

Example 


;♦♦♦*♦♦***♦******♦**♦*♦***♦*****♦**************♦*************, 

/ 

;  Function  2 AH:  Get  Date 

f 

;  long  get_date (pdow,pmonth,pday,pyear) 

;  char  *pdow, *pmonth, *pday; 

;  int  *pyear; 

;  Returns  the  date  packed  into  a  long: 

;  low  byte  =  day  of  month 

;  next  byte  =  month 

;  next  word  =  year. 


(more) 
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cProc  get_date, PUBLIC,  ds 

parmDP  pdow 

parmDP  pmonth 

parmDP  pday 

parmDP  pyear 

cBegin 

mov  ah, 2 ah 

int  21h 

loadDP  ds,bx,pdow 
mov  [bx],al 

loadDP  ds,bx, pmonth 
mov  [bx],dh 

loadDP  ds,bx,pday 
mov  [bx] , dl 

loadDP  ds,bx, pyear 
mov  [bx] , cx 

mov  ax,dx 

mov  dx ,  cx 

cEnd 


Set  function  code. 

Get  date  info  from  MS-DOS. 

DS:BX  =  pointer  to  dow. 

Return  dow. 

DS:BX  =  pointer  to  month. 

Return  month. 

DS:BX  =  pointer  to  day. 

Return  day. 

DS:BX  =  pointer  to  year. 

Return  year. 

Pack  day,  month,  . . . 

...  and  year  into  return  value. 
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Interrupt  21H  (33)  1.0  and  later 

Function  2BH  (43) 

Set  Date 


Function  2BH  accepts  binary  values  for  the  year,  month,  and  day  of  the  month  and  stores 
them  in  the  system’s  date  counter  as  the  number  of  days  since  January  1, 1980. 

ToCaU 


AH  =  2BH 

CX  =  year  (1980  through  2099) 

DH  =  month  (1  through  12) 

DL  =  day  (1  through  31) 

Returns 

AL  =OOH  system  date  updated 

FFH  invalid  date  specified 

Programmer’s  Note 

•  The  year  must  be  a  l6-bit  value  in  the  range  1980  through  2099.  Values  outside  this 
range  are  not  accepted.  In  addition,  supplying  only  the  last  two  digits  of  the  year 
causes  an  error. 

Related  Functions 


2AH  ((}et  Date) 

2CH  (Get  Time) 

2DH  (Set  Time) 

Example 

.it::ii:it:itiH:H!HiH!H!HiHirHtitiHt*Ht;tiitlii(li*****illi*********************************** 

;  Function  2BH:  Set  Date 

f 

;  int  set-date (month, day,  year) 

;  char  month, day; 

;  int  year; 

;  Returns  0  if  date  was  OK,  -1  if  not. 


(more) 
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cProc 

set_date, PUBLIC 

parmB 

month 

parmB 

day 

parmW 

year 

cBegin 

mov 

dh, month 

mov 

dl, day 

mov 

cx, year 

mov 

ah,2bh 

int 

21h 

cbw 

cEnd 

;  Get  new  month. 

;  Get  new  day. 

;  Get  new  year. 

;  Set  function  code. 

;  Ask  MS-DOS  to  change  date 
;  Return  0  or  -1  . 
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Interrupt  21H  (33)  1.0  and  later 

Function  2CH  (44) 

Get  Time 


Function  2CH  reports  the  current  system  time — hours  (based  on  a  24-hour  clock), 
minutes,  seconds,  and  hundredths  of  a  second — in  binary  form. 

To  Call 

AH  =  2CH 

Returns 

CH  =  hours  (0  through  23) 

CL  =  minutes  (0  through  59) 

DH  =  seconds  (0  through  59) 

DL  =  hundredths  of  second  (0  through  99) 

Programmer’s  Note 

•  The  accuracy  of  the  time  returned  by  Function  2CH  depends  on  the  accuracy  of  the 
system’s  timekeeping  hardware.  On  systems  unable  to  resolve  time  to  the  hundredth 
of  a  second,  the  DL  register  may  contain  either  OOH  or  an  approximate  value  calcu¬ 
lated  by  an  MS-DOS  algorithm. 

Related  Functions 

2AH  (Get  Date) 

2BH  (Set  Date) 

2DH  (Set  Time) 

Example 


Function  2CH:  Get  Time 


long  get_time (phour, pmin, psec, phund) 
char  *phour, *pmin, *psec, *phund; 

Returns  the  time  packed  into  a  long: 
low  byte  =  hundredths 
next  byte  =  seconds 
next  byte  =  minutes 
next  byte  =  hours . 


(more) 
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cProc 

get_time, PUBLIC, ds 

parmDP 

phour 

parmDP 

pmin 

parmDP 

psec 

parmDP 

phund 

cBegin 

mov 

ah, 2ch 

int 

21h 

loadDP 

ds,bx, phour 

mov 

[bx] , ch 

loadDP 

ds,bx,pmin 

mov 

[bx],cl 

loadDP 

ds,bx,psec 

mov 

[bx],dh 

loadDP 

ds,bx, phund 

mov 

[bx],dl 

mov 

ax,  dx 

mov 

dx,  cx 

cEnd 


Set  function  code. 

Get  time  from  MS-DOS. 

DS:BX  =  pointer  to  hour. 
Return  hour. 

DS:BX  =  pointer  to  min. 
Return  min. 

DSiBX  =  pointer  to  sec. 
Return  sec. 

DS:BX  =  pointer  to  hund. 
Return  hund. 

Pack  seconds,  hundredths, 

. . .  minutes,  and  hour  into 
return  value. 
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Interrupt  21H  (33)  1.0  and  later 

Function  2DH  (45) 

Set  Time 


Function  2DH  accepts  binary  values  for  the  hour  (based  on  a  24-hour  clock),  minute, 
second,  and  hundredths  of  a  second  and  stores  them  in  the  operating  system’s  time 
counter. 

ToCaU 

AH  =  2DH 

CH  =  hours  (0  through  23) 

CL  =  minutes  (0  through  59) 

DH  =  seconds  (0  through  59) 

DL  =  hundredths  of  second  (0  through  99) 

Returns 

AL  =  OOH  time  successfully  updated 

FFH  invalid  time  specified 

Programmer’s  Note 

•  On  systems  that  are  unable  to  resolve  the  time  to  the  hundredth  of  a  second,  the  DL 

register  should  be  set  to  OOH  before  Function  2DH  is  called. 

Related  Functions 

2AH  (Get  Date) 

2BH  (Set  Date) 

2CH  (Get  Time) 

Example 


Function  2DH:  Set  Time 

int  set_time (hour, min, sec, hund) 
char  hour, min, sec, hund; 

Returns  0  if  time  was  OK,  -1  if  not. 


(more) 
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cProc 

set_time, PUBLIC 

parmB 

hour 

parmB 

min 

parmB 

sec 

parmB 

hund 

cBegin 

mov 

ch, hour 

mov 

cl, min 

mov 

dh, sec 

mov 

dl, hund 

mov 

ah,2dh 

int 

21h 

cbw 

cEnd 


Get  new  hour. 

Get  new  minutes . 

Get  new  seconds. 

Get  new  hundredths. 

Set  function  code. 

Ask  MS-DOS  to  change  time 
Return  0  or  -1 . 
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Interrupt  21H  (33)  1.0  and  later 

Function  2EH  (46) 

Set/Reset  Verify  Flag 


Function  2EH  turns  the  internal  MS-DOS  verify  flag  on  or  off,  thus  determining  whether 
MS-DOS  verifies  disk  write  operations. 

ToCaU 

AH  =  2EH 

AL  =  OOH  turn  verify  off 

OlH  turn  verify  on 

DL  =  OOH  (MS-DOS  versions  1.x  and  2.x  only) 

Returns 

Nothing 

Programmer’s  Notes 

•  If  the  verify  flag  is  on,  MS-DOS  requests  any  block-device  driver  to  verify  each  sector 
written.  If  the  driver  does  not  support  read-after-write  verification,  the  verify  flag  has 
no  effect. 

•  Function  54H  (Get  Verify  Flag)  can  be  used  to  check  the  current  setting  of  the  verify 
flag. 

•  Verifying  data  slows  disk  access  during  write  operations.  Because  disk  errors  are  rare, 
the  default  setting  of  the  verify  flag  is  off. 

•  Verification  can  be  controlled  at  the  user  level  with  the  MS-DOS  VERIFY  command. 

Related  Function 

54H  (Get  Verify  Flag) 

Example 


Function  2EH:  Set /Reset  Verify  Flag 

int  set—verify (newvflag) 
char  newvflag; 

Returns  0 . 

3|c;|c%:|e:|c:|c:|c4c:|c4c4c4s4s4c4;4e:ie4c:|(4e4c:ic4c4e4c4c3|c9ie:ie:|e:|c:(c4c:|e4c4e;i(4c9ic:|c)fc%i|E4c)|c4e9|c:ie:|e4c:|e4c4c3)e4e4e4c4c:je4c 


(more) 
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cProc  set_verify, PUBLIC 
parmB  newvflag 
cBegin 

mov  al, newvflag 

mov  ah, 2 eh 

int  21  h 

xor  ax, ax 

cEnd 


;  Get  new  value  of  verify  flag. 
;  Set  function  code. 

;  Ask  MS-DOS  to  store  flag. 

;  Return  0. 
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Interrupt  21H  (33)  2.0  and  later 

Function  2FH  (47) 

Get  DTA  Address 


Function  2FH  returns  the  current  disk  transfer  area  (DTA)  address. 

ToCaU 

AH  =  2FH 

Returns 

ES:BX  =  segment;offset  of  current  DTA  address 

Programmer’s  Notes 

•  Function  2FH  returns  the  base  address  of  the  current  DTA.  MS-DOS  has  no  way  of 
knowing  the  size  of  the  buffer  at  that  address;  the  program  must  ensure  that  the  buffer 
pointed  to  by  the  DTA  address  is  large  enough  to  hold  any  records  transferred  to  it. 

•  The  current  DTA  address  can  be  set  with  Function  lAH  (Set  DTA  Address).  If  the  DTA 
address  is  not  set,  MS-DOS  uses  a  default  buffer  of  128  bytes  located  at  offset  80H  in 
the  program  segment  prefix  (PSP). 

Related  Function 

lAH  (Set  DTA  Address) 

Example 


Function  2FH:  Get  DTA  Address 
char  far  *get_DTA() 

Returns  a  far  pointer  to  the  DTA  buffer. 


cProc  get_DTA, PUBLIC 
cBegin 

mov  ah,2fh 

int  21 h 

mov  ax,bx 

mov  dx,es 

cEnd 


;  Set  function  code. 

;  Ask  MS-DOS  for  current  DTA  address. 
;  Return  offset  in  AX. 

;  Return  segment  in  DX. 
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Interrupt  21H  (33)  2.0  and  later 

Function  30H  (48) 

Get  MS-DOS  Version  Number 


Function  30H  returns  the  major  and  minor  version  numbers  for  MS-DOS  versions  2.0  and 
later. 

ToCaU 

AH  =  30H 

AL  =  OOH 

Returns 

AL  =  major  version  number  (for  example,  3  for  MS-DOS  version  3.x) 

AH  =  minor  version  number  (for  example,  OAH  for  MS-DOS  version  x.  10) 

BH  =  original  equipment  manufacturer’s  (OEM’s)  serial  number  (OEM 

dependent — usually  OOH  for  PC-DOS,  OFFH  or  other  values  for  MS-DOS) 
BL:CX  =  24-bit  user  serial  number  (optional;  OEM  dependent) 

Programmer's  Notes 

•  With  MS-DOS  versions  1.x,  Function  30H  returns  OOH  in  the  AL  register;  the  value 
returned  in  AH  is  variable  and  not  representative  of  the  actual  1.x  minor  version 
number. 

•  Function  30H  supplies  the  MS-DOS  version  number  to  an  application  program  that 
might  require  features  of  the  operating  system  that  are  not  available  in  all  versions.  If 
an  application  attempts  to  use  such  features  with  the  wrong  version  of  MS-DOS,  the 
results  are  unpredictable. 

Applications  requiring  MS-DOS  version  2.0  or  later  should  use  Function  30H  to  check 
for  versions  1.x.  Because  versions  1.x  do  not  contain  predefined  handles  for  displaying 
error  messages.  Function  02H  (Character  Output)  or  Function  09H  (Display  String) 
must  be  used  with  those  versions.  Similarly,  applications  running  under  versions  1.x 
cannot  terminate  through  a  call  to  Function  4CH  (Terminate  Process  with  Return 
Code). 

Related  Functions 

None 
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Example 

;  Function  30H:  Get  MS-DOS  Version  Number 

;  int  DOS_version 0 

;  Returns  number  of  MS-DOS  version,  with 

;  major  version  in  high  byte, 

;  minor  version  in  low  byte. 

.^f:tiilf;im:lti*ilf:ii*iH*iitHtitt4t:ti:ii:iL:iiit‘***************************^************ 

cProc  DOS_version, PUBLIC 
cBegin 

mov  ax,3000H  ;  Set  function  code  and  clear  AL. 

int  21 h  ;  Ask  MS-DOS  for  version  number, 

xchg  al,ah  ;  Swap  major  and  minor  numbers. 

cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  31H  (49) 

Terminate  and  Stay  Resident 


Function  31H  terminates  a  program  and  returns  control  to  the  parent  process  (usually 
COMMAND.COM)  but  keeps  the  terminated  program  resident  in  memory. 

To  Call 

AH  =  31H 
AL  =  return  code 

DX  =  number  of  paragraphs  of  memory  to  be  reserved  for  current  process 

Returns 

Nothing 

Programmer’s  Notes 

•  The  following  interrupt  vectors  are  restored  from  the  program  segment  prefix  (PSP) 

of  the  terminated  program: 


PSP  Offset  Vector  for  Interrupt 

OAH  Interrupt  22H  (terminate  routine) 

OEH  Interrupt  23H  (Control-C  handler) 

12H  Interrupt  24H  (critical  error  handler)  (versions  2.0  and  later.) 

•  The  minimum  amount  of  memory  a  process  can  reserve  is  6  paragraphs  (60H  bytes), 
which  constitutes  the  initial  portion  of  the  process’s  PSP  (including  the  reserved 
areas). 

•  The  amount  of  memory  required  by  the  program  is  not  necessarily  the  same  as  the 
size  of  the  file  that  holds  the  program  on  disk.  The  program  must  allow  for  its  PSP  and 
stack  in  the  amount  of  memory  reserved;  on  the  other  hand, the  memory  occupied  by 
code  and  data  used  only  during  program  initialization  frequently  can  be  discarded  as 
a  side  effect  of  the  Function  31H  call. 

Before  Function  31H  is  called,  memory  allocated  to  the  terminating  process’s  environ¬ 
ment  block  should  be  released  by  loading  ES  with  the  segment  value  at  offset  2CH  in 
the  PSP  (the  segment  address  of  the  environment)  and  calling  Function  49H  (Free 
Memory  Block). 

•  The  terminating  process  should  return  a  completion  code  in  the  AL  register.  If  the 
program  terminates  normally,  the  return  code  should  be  OOH.  A  return  code  of  OlH  or 
greater  usually  indicates  that  termination  was  caused  by  an  error  encountered  by 

the  process. 
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The  parent  process  can  retrieve  the  return  code  with  Function  4DH  (Get  Return  Code 
of  Child  Process).  If  control  returns  to  COMMAND.COM,  the  return  code  can  be 
tested  with  an  ERRORLEVEL  statement  in  a  batch  file. 

•  After  terminating  the  current  process,  MS-DOS  attempts  to  set  the  program’s  memory 
allocation  to  the  amount  specified  in  DX. 

•  Function  31H  is  most  often  used  for  memory-resident  utilities  and  subroutine  libraries 
that  can  be  accessed  using  interrupts. 

•  This  function  is  preferable  to  Interrupt  27H  (Terminate  and  Stay  Resident)  because  it 
allows  programs  that  are  larger  than  64  KB  to  remain  resident,  allows  the  terminating 
program  to  pass  a  return  code  to  the  parent  process,  and  does  not  require  that  the  CS 
register  contain  the  PSP  address. 

Related  Functions 

48H  (Allocate  Memory  Block) 

49H  (Free  Memory  Block) 

4AH  (Resize  Memory  Block) 

4BH  (Load  and  Execute  Program) 

4CH  (Terminate  Process  with  Return  Code) 

4DH  (Get  Return  Code  of  Child  Process) 

Example 

;  Function  31 H:  Terminate  and  Stay  Resident  ; 

;  void  keep_process (exit_code, nparas)  ; 

;  int  exit—code, nparas;  ; 

;  Does  NOT  return!  ; 

•******^/:****Mli*******************************:ii:ti*i^‘*****it:*******f 

cProc  keep_process,  PUBLIC 
parmB  exit_code 
parmW  nparas 
cBegin 

mov 

mov 

mov 

int 

cEnd 


al,exit_code  ;  Get  return  code. 

dx, nparas  ;  Set  DX  to  number  of  paragraphs  the 

;  program  wants  to  keep. 
ah,31h  ;  Set  function  code. 

21 h  ;  Ask  MS-DOS  to  keep  process. 
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Interrupt  21H  (33)  2.0  and  later 

Function  33H  (51) 

Get/Set  Control-C  Check  Flag 


Function  33H  gets  or  sets  the  status  of  the  Control-C  check  flag. 

ToCaU 


AH  =  33H 

AL  =  OOH  get  current  Control-C  check  flag 

OlH  set  Control-C  check  flag  to  value  in  DL 

IfALis  OlH: 

DL  =  OOH  set  Control-C  check  flag  to  off 
OlH  set  Control-C  check  flag  to  on 

Returns 


AL  =00H 
FFH 


flag  set  successfully 

code  in  AL  on  call  not  OOH  or  OlH 


If  AL  was  OOH  on  call: 

DL  =00H  Control-C  check  flag  off 

OlH  Control-C  check  flag  on 

Programmer's  Notes 

•  If  the  Control-C  check  flag  is  off,  MS-DOS  checks  for  a  Control-C  entered  at  the  key¬ 
board  only  during  servicing  of  the  character  I/O  functions,  OlH  through  OCH.  If  the 
Control-C  check  flag  is  on,  MS-DOS  also  checks  for  user  entry  of  a  Control-C  during 
servicing  of  other  functions,  such  as  file  and  record  operations. 

•  The  state  of  the  Control-C  check  flag  affects  all  programs.  If  a  program  needs  to 
change  the  state  of  Control-C  checking,  it  should  save  the  original  flag  and  restore  it 
before  terminating. 

Related  Functions 


None 
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Example 


Function  33H:  Get /Set  Control-C  Check  Flag 

int  controlC (func, state) 
int  func, state; 

Returns  current  state  of  Control-C  flag. 


cProc  controlC, PUBLIC 
parmB  func 
parmB  state 
cBegin 

mbv  al,func 

mov  dl, state 

mov  ah,33h 

int  21 h 

mov  al,dl 

cbw 

cEnd 


;  Get  set /reset  function. 

;  Get  new  value  if  present. 

;  MS-DOS  ''C  check  function. 

;  Call  MS-DOS. 

;  Return  current  state. 

;  Clear  high  byte  of  return  value. 
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Interrupt  21H  (33)  2.0  and  later 

Function  34H  (52) 

Return  Address  of  InDOS  Flag 


Function  34H  returns  the  address  of  the  InDOS  flag,  which  reflects  the  current  state  of 

Interrupt  21H  function  processing. 

Note:  Microsoft  cannot  guarantee  that  the  information  in  this  entry  will  be  valid  for  future 

versions  of  MS-DOS. 

ToCaU 

AH  =  34H 

Returns 

ES:BX  =  segment:offset  of  InDOS  flag 

Programmer’s  Notes 

•  The  InDOS  flag  is  a  byte  within  the  MS-DOS  kernel.  The  value  in  InDOS  is  incre¬ 
mented  when  MS-DOS  begins  execution  of  an  Interrupt  21H  function  and  decre¬ 
mented  when  MS-DOS’s  processing  of  that  function  is  completed.  Thus,  the  value 
of  InDOS  is  zero  only  when  no  Interrupt  21H  processing  is  occurring. 

•  The  InDOS  flag  is  one  of  the  elements  used  in  terminate-and-stay-resident  (TSR)  pro¬ 
grams  to  determine  when  the  TSR  can  be  executed  safely. 

Related  Functions 


None 

Example 

/ 

;  Function  34H;  Get  Return  Address  of  InDOS  Flag 

;  char  far  *inDOS_ptr() 

;  Returns  a  far  pointer  to  the  MS-DOS  inDOS  flag. 


cProc 

inDOS. 

_ptr, PUBLIC 

cBegin 

mov 

ah,34h 

int 

21h 

mov 

ax,bx 

mov 

dx,  es 

cEnd 

;  InDOS  flag  function. 
;  Call  MS-DOS. 

;  Return  offset  in  AX. 
;  Return  segment  in  DX 
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Interrupt  21H  (33)  2.0  and  later 

Function  35H  (53) 

Get  Interrupt  Vector 


Function  35H  returns  the  address  stored  in  the  interrupt  vector  table  for  the  handler 
associated  with  the  specified  interrupt. 

ToCaU 

AH  =  35H 

AL  =  interrupt  number 

Returns 

ES:BX  =  segment:offset  of  handler  for  interrupt  specified  in  AL 

Programmer’s  Note 

•  Interrupt  vectors  should  always  be  read  with  Function  35H  and  set  with  Function  25H 
(Set  Interrupt  Vector).  Programs  should  never  attempt  to  read  or  change  interrupt 
vectors  directly  in  memory. 

Related  Function 

25H  (Set  Interrupt  Vector) 

Example 


Function  35H:  Get  Interrupt  Vector 

typedef  void  (far  *FCP)(); 

FCP  get_vector (intnum) 
int  intnum; 

Returns  a  far  code  pointer  that  is  the 
segment : offset  of  the  interrupt  vector. 


cProc  get_vector, PUBLIC 

parmB  intnum 

cBegin 

mov  al, intnum 

mov  ah, 35h 

int  21 h 

mov  ax,bx 

mov  dx,es 

cEnd 


;  Get  interrupt  number  into  AL 
;  Select  "get  vector”  function 
;  Call  MS-DOS. 

;  Return  vector  offset. 

;  Return  vector  segment . 
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IlltClTllJ>t  21H  C33)  2.0  and  later 

Function  36H  (54) 

Get  Disk  Free  Space 


Function  36H  returns  disk-storage  information  for  the  specified  drive. 

ToCaU 

AH  =  36H 

DL  =  drive  specification  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 

Returns 

If  function  is  successful: 

AX  =  number  of  sectors  per  cluster 

BX  =  number  of  clusters  available 

CX  =  number  of  bytes  per  sector 

DX  =  number  of  clusters  on  drive 

If  function  is  not  successful: 

AX  =FFFFH  invalid  drive  number  in  DL 

Programmer’s  Notes 

•  The  AX  register  should  be  checked  for  a  value  of  FFFFH  (error)  before  information 
returned  by  this  function  is  used. 

•  The  number  of  bytes  of  free  storage  remaining  on  the  disk  can  be  calculated  by 
multiplying  available  clusters  times  sectors  per  cluster  times  bytes  per  sector  (BX  • 
AX*CX). 

•  Function  36H  regards  “lost”  clusters  (clusters  that  are  allocated  in  the  file  allocation 
table  [FATl  but  do  not  belong  to  a  file)  as  being  in  use  and  subtracts  them  from  the 
amount  of  available  storage,  exactly  as  if  they  were  allocated  to  a  file. 

•  With  MS-DOS  versions  2.0  and  later.  Function  36H  should  be  used  in  preference  to  the 
FCB  Functions  IBH  ((Set  Default  Drive  Data)  and  ICH  (Get  Drive  Data). 

Related  Functions 

IBH  (Get  Default  Drive  Data) 

ICH  (Get  Drive  Data) 
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Example 

.  ♦♦♦♦*♦♦*♦♦*****♦♦♦♦♦♦♦♦♦*♦♦**♦♦♦♦♦**********♦**♦♦♦***♦******. 

;  Function  36H:  Get  Disk  Free  Space  ; 

;  long  free_space (drive_ltr)  ; 

;  char  drive_ltr;  ; 

;  / 
;  Returns  the  number  of  bytes  free  as  ; 

;  a  long  integer.  ; 

.  ************it‘if***********iH*^*i!i**itm^**************************  f 

cProc  free_space, PUBLIC 
parmB  drive_ltr 


cBegin 

mov 

dl,  drive_ltr 

;  Get  drive  letter. 

or 

dl,dl 

;  Leave  0  alone. 

jz 

fsp 

and 

dl,not  20h 

;  Convert  letter  to  uppercase. 

sub 

dl, 'A'-1 

;  Convert  to  drive  number:  'A'  =  1, 

/  *B*  =2,  etc. 

fsp: 

mov 

ah,36h 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  to  get  disk  information 

mul 

cx 

;  Bytes/sector  *  sectors/cluster 

mul 

bx 

;  *  free  clusters. 

cEnd 
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Interrupt  2m  (33)  2,0  and  later 

Function  38H  (56) 

Get/Set  Current  Country:  Get  Current  Country 


Function  38H  includes  two  subfunctions  that  either  get  or  set  country  data,  depending  on 
the  value  in  the  DX  register  when  the  function  is  called. 

With  MS-DOS  versions  2.0  and  later,  if  DX  contains  any  value  other  than  FFFFH,  the  Get 
Current  Country  subfunction  is  invoked.  Information  on  date,  currency,  and  other  country- 
specific  formats  is  then  returned  in  a  buffer  specified  by  the  calling  program.  The  country 
code  is  usually  the  same  as  the  country’s  international  telephone  prefix. 

ToCaU 

AH  =  38H 

With  MS-DOS  versions  2.x: 

AL  =00H  current  country 

DS:DX  =  segment:offset  of  32-byte  buffer 

With  MS-DOS  versions  3.x: 

AL  =  OOH  current  country 

01  -FEH  country  code  between  1  and  254 

FFH  country  code  of  255  or  greater,  specified  in  BX 

BX  =  country  code  if  AL  =  FFH 

DS:DX  =  segment:offset  of  34-byte  buffer 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

BX  =  country  code  (MS-DOS  version  3.x  only) 

DS:DX  =  segment:offset  of  buffer  containing  country  information 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

02H  invalid  country  code 
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Programmer’s  Notes 

•  With  MS-DOS  versions  2.x,  the  Get  Current  Country  subfunction  returns  the  following 
information  for  the  current  country  in  the  32-byte  country-data  buffer  (ASCIIZ  format 
is  an  ASCII  character  string  ending  in  a  zero  byte): 


Offset 

Type 

Description 

OOH 

Word 

Date  format: 

0  =  United  States  (m/d/y) 

1  =  Europe  (d/m/y) 

2  =  Japan  (y/m/d) 

02H 

ASCIIZ 

Currency  symbol 

04H 

ASCIIZ 

Character  used  as  thousands  separator 

06H 

ASCIIZ 

Character  used  as  decimal  separator 

OSH 

24  bytes 

Reserved 

With  MS-DOS  versions  3.x,  the  Get  Current  Country  subfunction  returns  the  following 
information  for  the  specified  country  in  the  34-byte  country-data  buffer: 

Offset 

Type 

Description 

OOH 

Word 

Date  format: 

0  =  United  States  (m/d/y) 

1  =  Europe  (d/m/y) 

2  =  Japan  (y/m/d) 

02H 

ASCIIZ 

Currency  symbol  (5  bytes,  as  opposed  to  2  in  versions  2.x 

of  MS-DOS) 

07H 

ASCIIZ 

Character  used  as  thousands  separator 

09H 

ASCIIZ 

Character  used  as  decimal  separator 

OBH 

ASCIIZ 

Character  used  as  date  separator 

ODH 

ASCIIZ 

Character  used  as  time  separator 

OFH 

Byte 

Position  of  currency  symbol;  possible  values  are 

OOH  Currency  symbol  precedes  value  with 
no  space 

OlH  Currency  symbol  follows  value  with 

no  space 

02H  Currency  symbol  precedes  value  with 

one  space 

03H  Currency  symbol  follows  value  with 

one  space 

lOH  Byte  Number  of  decimal  places  in  currency 


(more) 


1288  The  MS-DOS  Encyclopedia 


Interrupt  21H  Function  38H 


Offset 

Type 

Description 

IIH 

Byte 

Time  format  (OOH  =  12-hour  clock;  OlH  =  24-hour  clock) 

12H 

Dword 

Case-mapping  call  address  (^See  Programmer’s  Notes 
below.) 

16H 

ASCIIZ 

Character  used  as  separator  in  data  lists 

18H 

10  bytes 

Reserved 

•  The  case-mapping  call  address  (MS-DOS  versions  3.x  only)  is  the  segment:offset 
of  a  FAR  procedure  that  performs  country-specific  mapping  on  ASCII  characters  in 
the  range  80H  through  OFFH.  The  character  to  be  mapped  must  be  placed  in  the  AL 
register  before  the  call  is  made.  If  the  character  has  an  uppercase  value,  that  value  is 
returned  in  AL.  If  the  character  has  no  such  value,  AL  is  unchanged. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

38H  (Set  Current  Country  subfunction) 

Example 


Function  38H:  Get /Set  Current  Country  Data 

int  country_info (country, pbuffer) 
char  country, *pbuffer; 

Returns  -1  if  the  "country”  code  is  invalid. 


cProc  country_info, PUBLIC, ds 

parmB  country 
parmDP  pbuffer 
cBegin 

mov  al, country 

loadDP  ds, dx, pbuffer 
mov  ah, 38h 

int  21h 

jnb  cc_ok 

mov  ax,-1 

cc_ok: 

cEnd 


Get  country  code. 

Get  buffer  pointer  (or  -1 ) 
Set  function  code. 

Ask  MS-DOS  to  get  country 
information . 

Branch  if  country  code  OK. 
Else  return  -1 . 
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Interrupt  21H  (33)  3.0  and  later 

Function  38H  (56) 

Get/Set  Current  Country:  Set  Current  Country 


Function  38H  includes  two  subfunctions  that  either  get  or  set  country  data,  depending 
on  the  value  in  the  DX  register  when  the  function  is  called. 

With  MS-DOS  versions  3.0  and  later,  the  Set  Current  Country  subfunction  is  invoked  if 
Function  38H  is  called  with  DX  =  FFFFH  (-1).  This  subfunction  selects  the  country  for 
which  subsequent  calls  to  Get  Current  Country  will  return  information.  The  country  code 
used  with  this  function  is  usually  the  same  as  the  country’s  international  telephone  prefix. 

ToCaU 

AH  =  38H 

AL  =  country  code  for  a  code  less  than  255 

FFH  for  country  code  of  255  or  greater,  specified  in  BX 

BX  =  country  code  if  AL  =  FFH 
DX  =  FFFFH  (-1) 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

02H  invalid  country  code 

Programmer's  Notes 

•  MS-DOS  normally  uses  the  country  code  associated  with  the  current  KEYBxx 
keyboard  driver  file,  if  any.  Otherwise,  the  default  country  code  is  OEM  dependent. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

38H  (Get  Current  Country  subfunction) 

Example 

See  Function  38H  Subfunction  Get  Current  Country  for  example. 
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Interrupt  21H  (33)  2  0  and  later 

Function  39H  (57) 

Create  Directory 


Function  39H  creates  a  subdirectory  using  the  specified  path. 

ToCaU 

AH  =  39H 

DS:DX  =  segment:offset  of  ASCIIZ  path 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

03H  path  not  found 

05H  access  denied 

Programmer's  Notes 

•  The  path  must  be  a  null-terminated  ASCII  string  (ASCIIZ). 

•  MS-DOS  places  the  current  directory  (.)  and  parent  directory  (..)  entries  in  all  new 
directories. 

•  Function  39H  returns  error  code  05H  (access  denied)  in  the  following  cases: 

-  File  or  directory  with  the  same  name  already  exists  in  the  specified  path. 

-  Parent  directory  is  the  root  directory  and  the  root  directory  is  full. 

-  Path  specifies  a  device. 

-  Program  is  running  on  a  network  under  MS-DOS  version  3.1  or  later  and  the  user 
does  not  have  Create  access  to  the  parent  directory. 

•  Function  59H  (Cjet  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

3AH  (Remove  Directory) 

3BH  (Change  Current  Directory) 

47H  (Get  Current  Directory) 
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Example 

.^^^iHi:ii*:HiHiii:it:************************************************** 

;  Function  39H:  Create  Directory 

/ 

;  int  make_dir (pdirpath) 

;  char  *pdirpath; 

. ;  Returns  0  if  directory  created  OK, 

;  otherwise  returns  error  code. 

.illi:ti********************************************************** 


cProc  make_dir, PUBLIC, ds 

parmDP  pdirpath 

cBegin 

loadDP  ds, dx, pdirpath 
mov  ah,39h 

int  21 h 

jb  md_err 

xor  ax, ax 

md_err : 
cEnd 


Get  pointer  to  pathname. 

Set  function  code. 

Ask  MS-DOS  to  make  new  subdirectory. 
Branch  on  error. 

Else  return  0. 
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Interrupt  21H  (33)  2  0  and  later 

Function  3AH  (58) 

Remove  Directory 


Function  3AH  removes  (deletes)  the  specified  subdirectory. 

ToCaU 

AH  =  3AH 

DS:DX  =  segment:offset  of  ASCIIZ  path 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

03H  path  not  found 

05H  access  denied 

lOH  current  directory  was  specified 

Programmer's  Notes 

•  The  path  must  be  a  null-terminated  ASCII  string  (ASCIIZ). 

•  Function  3AH  returns  error  code  05H  (access  denied)  in  the  following  cases: 

-  Directory  is  not  empty. 

-  Root  directory  was  specified. 

-  Current  directory  was  specified. 

-  Path  does  not  specify  a  valid  directory. 

-  Directory  is  malformed  (.  and ..  not  first  two  entries). 

-  User  has  insufficient  access  rights  on  a  network  running  under  MS-DOS  version  3.1 
or  later. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

39H  (Create  Directory) 

3BH  (Change  Current  Directory) 

47H  (Get  Current  Directory) 
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Example 

•  iiiiHHiit:HtHcitiitiHidlf*Ht************************************************ 

;  Function  3AH:  Remove  Directory 

;  int  remove_dir (pdirpath) 

;  char  *pdirpath; 

/ 

;  Returns  0  if  directory  was  removed, 

;  otherwise  returns  error  code. 


cProc  remove_dir, PUBLIC,  ds 

parmDP  pdirpath 

cBegin 


loadDP 

ds , dx , pdi rpat h 

;  Get  pointer  to  pathname. 

mov 

ah, 3ah 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  to  delete  subdirectory 

jb 

rd_err 

;  Branch  on  error. 

xor 

ax, ax 

;  Else  return  0. 

rd_err ; 

cEnd 

1294  The  MS-DOS  Encycl(^dia 


Interrupt  21H  Function  3BH 


Interrupt  21H  (33)  2.0  and  later 

Function  3BH  (59) 

Change  Current  Directory 


Function  3BH  changes  the  current  directory  to  the  specified  path. 

To  Call 

AH  =  3BH 

DS:DX  =  segment:offset  of  ASCIIZ  path 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

03H  path  not  found 

Programmer’s  Notes 

•  The  path  must  be  a  null-terminated  ASCII  string  (ASCIIZ). 

•  Before  a  call  to  Function  3BH,  Function  47H  (Get  Current  Directory)  can  be  used 

to  determine  the  current  directory  so  that  the  original  directory  can  be  restored  later 
(for  example,  on  termination  of  the  program). 

•  Function  3BH  can  be  used  with  programs  that  rely  on  either  FCB-based  or  handle- 
based  calls.  It  is  the  only  method  of  changing  the  current  directory  that  is  supported 
by  MS-DOS. 

•  The  path  string  is  limited  to  a  total  of  64  characters,  including  separators. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

39H  (Create  Directory) 

3AH  (Remove  Directory) 

47H  (Get  Current  Directory) 
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Example 


Function  3BH:  Change  Current  Directory 

int  change_dir (pdirpath) 
char  *pdirpath; 

Returns  0  if  directory  was  changed, 
otherwise  returns  error  code. 


cProc  change_dir, PUBLIC, ds 

parmDP  pdirpath 

cBegin 

loadDP  ds, dx, pdirpath 
mov  ah, 3bh 

int  21 h 

jb  cd_err 

xor  ax, ax 

cd_err : 
cEnd 


;  Get  pointer  to  pathname. 
;  Ask  MS-DOS  to  move  to 
;  different  directory. 

;  Branch  on  error. 

/  Else  return  0 . 
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IntelTUpt  21H  C33)  2.0  and  later 

Function  3CH  (60) 

Create  File  with  Handle 


Function  3CH  creates  a  file,  assigns  it  the  attributes  specified,  and  returns  a  l6-bit  handle 
for  the  file.  If  the  named  file  already  exists.  Function  3CH  opens  it  and  truncates  it  to  zero 
length. 

ToCaU 

AH  =  3CH 

CX  =  attribute 

DS:DX  =  segment:offset  of  ASCIIZ  pathname 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX  =  handle  number 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

03H  path  not  found 

04H  too  many  open  files 

05H  access  denied 

Programmer's  Notes 

•  Function  3CH  is  preferable  to  Function  16H  (Create  File  with  FCB)  for  creating  a  file 
because  it  supports  full  pathnames.  Function  16H  should  be  used  only  if  compatibility 
with  versions  1.x  of  MS-DOS  is  required. 

•  The  pathname  must  be  a  null-terminated  ASCII  string  (ASCIIZ). 

•  Bits  0  through  2  of  the  2-byte  file  attribute  in  CX  determine  whether  the  file  is  normal, 
read-only,  hidden,  or  system.  The  attribute  codes  are 

-  OOH  normal  file 

-  OlH  read-only  file 

-  02H  hidden  file 

-  04H  system  file 

Bits  3  through  5  are  associated  with  volume  labels,  subdirectories,  and  archive  files. 
The  volume  and  subdirectory  bits  are  invalid  for  Function  3CH  and  must  be  set  to  0. 
Bits  6  through  15  should  be  set  to  0  to  ensure  future  compatibility. 
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Values  can  be  combined  to  set  several  file  attributes.  For  example,  if  Function  3CH  is 
called  with  CX  =  0003H,  the  file  created  is  a  read-only  hidden  file. 

•  Because  Function  3CH  truncates  an  existing  file  to  zero  length,  any  information  pre¬ 
viously  in  the  file  is  lost.  Alternative  functions  that  protect  against  such  loss  include 
the  following: 

-  Function  3DH  (Open  File  with  Handle)  or  Function  4EH  (Find  First  File),  which 
can  be  used  to  check  for  the  previous  existence  of  the  file  before  Function  3CH  is 
called 

-  Function  5AH  (Create  Temporary  File),  which  creates  a  file  in  the  specified  sub¬ 
directory  and  gives  it  a  unique  name  assigned  by  MS-DOS 

-  Function  5BH  (Create  New  File),  which  is  similar  to  Function  3CH  but  fails  if  it 
finds  a  file  that  matches  the  specified  pathname 

•  After  creating  a  file.  Function  3CH  sets  the  position  of  the  file  pointer  to  0.  Thus,  the 
next  read  or  write  operation  takes  place  at  the  beginning  of  the  file. 

•  Function  3CH  returns  error  code  04H  (too  many  open  files)  if  no  handle  is  currently 
available.  With  MS-DOS  versions  3.2  and  earlier,  a  single  process  can  have  no  more 
than  20  files  open  at  one  time,  5  of  which  are  normally  assigned  to  the  standard 
devices. 

Error  code  05H  (access  denied)  is  returned  if  the  file  is  to  be  created  in  the  root  direc¬ 
tory  and  the  root  is  full  or  if  a  read-only  file  with  the  same  name  already  exists  in  the 
specified  subdirectory. 

•  On  networks  running  under  MS-DOS  version  3.1  or  later,  the  user  must  have  Create 
access  to  the  directory  containing  the  file  specified. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

16H  (Create  File  with  FCB) 

43H  (Get/Set  File  Attributes) 

5AH  (Create  Temporary  File) 

5BH  (Create  New  File) 

Example 


Function  3CH:  Create  File  with  Handle 

int  create (pfilepath, attr) 
char  ♦pfilepath; 
int  attr; 

Returns  -1  if  file  was  not  created, 
otherwise  returns  file  handle. 


(more) 
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cProc  create, PUBLIC, ds 
parmDP  pfilepath 
parmW  attr 
cBegin 

loadDP  ds,dx, pfilepath 

mov  cx,attr 

mov  ah, 3ch 

int  21 h 

jnb  cr_ok 

mov  ax,-1 

cr_ok: 

cEnd 


Get  pointer  to  pathname. 

Get  new  file's  attribute. 

Ask  MS-DOS  to  make  a  new  file. 

Branch  if  MS-DOS  returned  handle. 
Else  return  -1 . 
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Interrupt  21H  (33)  2.0  and  later 

Function  3DH  (61) 

Open  File  with  Handle 


Function  3DH  opens  the  specified  file  and  returns  a  l6-bit  handle  number  for  subsequent 
access  to  the  file. 

ToCaU 

AH  =  3DH 

With  versions  2.x  of  MS-DOS: 

AL  =  file-access  code: 


Bits 

Value 

Meaning 

3-7 

00000 

Reserved 

0-2 

000 

Read-only  access 

001 

Write-only  access 

010 

Read/write  access 

DS:DX  =  segmentioffset  of  ASCIIZ  pathname 

With  versions  3.x  of  MS-DOS: 

AL  =  file-access,  file-sharing,  and  inheritance  codes: 

Bits 

Value 

Meaning 

7  (inherit  bit) 

0 

Child  process  inherits  file 

1 

Child  process  does  not  inherit 

file 

4-6  (sharing  mode; 

000 

Compatibility  mode 

file  access  granted 

001 

Deny  read/write  access 

to  other  processes) 

010 

Deny  write  access 

oil 

Deny  read  access 

100 

Deny  none 

3 

0 

Reserved 

0-2  (access  code; 

000 

Read-only  access 

file  usage) 

001 

Write-only  access 

010 

Read/write  access 

DS:DX  =  segment:offset  of  ASCIIZ  pathname 
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Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX  =  handle  number 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

02H  file  not  found 

03H  path  not  found 

04H  too  many  open  files 

05H  access  denied 

OCH  invalid  access  code 

Programmer’s  Notes 

•  Function  3DH  is  preferable  to  Function  OFH  (Open  File  with  FCB)  because  it  allows 
the  use  of  pathnames.  Function  OFH  should  be  used  only  if  compatibility  with  ver¬ 
sions  1.x  of  MS-DOS  is  required. 

•  Function  3DH  opens  any  file  matching  the  pathname  in  DS:DX,  including  hidden  and 
system  files. 

•  The  pathname  must  be  a  null-terminated  ASCII  string  (ASCIIZ). 

•  Function  3DH  returns  error  code  04H  (too  many  open  files)  if  no  handle  is  currently 
available.  With  MS-DOS  versions  3.2  and  earlier,  a  single  process  can  have  no  more 
than  20  files  open  at  one  time,  5  of  which  are  normally  assigned  to  the  standard 
devices. 

Function  3DH  returns  error  code  05H  (access  denied)  if  the  pathname  specifies  a 
directory  or  volume  label  or  if  read/write  access  was  requested  for  a  read-only  file. 

Function  3DH  returns  error  code  OCH  (invalid  access  code)  if  bits  0-2  in  AL  contain 
any  value  other  than  000, 001,  or  010. 

•  With  MS-DOS  versions  2.x,  only  bits  0-2  of  the  byte  in  AL  are  meaningful;  they  should 
contain  the  type  of  access  allowed  for  the  file.  Bits  3-7  should  always  be  zero. 

With  MS-DOS  versions  3.0  and  later,  networking  capabilities  require  bits  4-7,  as  well 
as  0-2,  to  be  set.  (Bit  3  is  reserved  and  should  be  0.) 

Bit  7,  the  inherit  bit,  should  be  set  to  indicate  whether  child  processes  created  by  the 
current  process  with  Function  4BH  (Load  and  Execute  Program)  either  can  (0)  or  can¬ 
not  (1)  inherit  the  file.  When  a  process  inherits  a  file,  it  also  inherits  the  access  and 
sharing  modes. 
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Bits  4-6  are  called  the  “sharing  code”;  they  indicate  the  type  of  access  other  users  on 
the  network  can  have  to  the  file.  The  five  sharing  modes  and  the  conditions  under 
which  they  pertain  are  as  follows: 

-  mode  000  (compatibility).  Allows  other  programs  running  on  the  same  machine 
unlimited  access  to  the  file.  Programs  running  on  other  machines  cannot  access 
the  file  across  the  network  unless  it  has  the  read-only  attribute.  An  attempt  to  open 
the  file  in  compatibility  mode  fails  if  the  file  has  already  been  opened  with  any 
other  sharing  mode. 

-  001  (deny  read  and  write  access).  Provides  exclusive  access  to  the  file.  Any  subse¬ 
quent  attempts  by  others  (including  the  current  process)  to  open  the  file  fail.  This 
mode  fails  if  the  file  has  already  been  opened  in  compatibility  mode  or  for  read  or 
write  access,  even  by  the  current  process. 

-  010  (deny  write  access).  Allows  other  processes  to  open  the  file  for  read-only  ac¬ 
cess.  This  mode  fails  if  the  file  has  already  been  opened  in  compatibility  mode  or 
for  write  access  by  any  other  process. 

-  Oil  (deny  read  access).  Allows  other  processes  to  open  the  file  for  write-only  ac¬ 
cess.  This  mode  fails  if  the  file  has  already  been  opened  in  compatibility  mode  or 
for  read  access  by  any  other  process. 

-  100  (deny  none).  Similar  to  compatibility  mode,  but  does  not  allow  other  processes 
to  open  the  file  in  compatibility  mode.  This  mode  fails  if  the  file  has  already  been 
opened  in  compatibility  mode  by  any  other  process. 

•  When  the  file  is  opened,  the  position  of  the  file  pointer  is  set  to  0.  Function  42H 
(Move  File  Pointer)  can  be  used  to  change  its  position. 

•  With  MS-DOS  versions  3.0  and  later,  if  this  function  fails  because  of  a  file-sharing 
error,  the  operating  system  issues  an  Interrupt  24H  (Critical  Error  Handler  Address) 
with  error  code  02H  (drive  not  ready).  Function  59H  (Get  Extended  Error  Informa¬ 
tion)  must  be  used  to  find  the  extended  error  code  specifying  the  type  of  sharing 
violation  that  occurred. 

Related  Functions 

OFH  (Open  File  with  FCB) 

3EH  (Close  File) 

3FH  (Read  File  or  Device) 

40H  (Write  File  or  Device) 

42H  (Move  File  Pointer) 

43H  (Get/Set  File  Attributes) 

57H  (Get/Set  Date/Time  of  File) 
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Example 


Function  3DH:  Open  File  with  Handle 

int  open (pfilepath, mode) 

char  *pfilepath;  int  mode; 

Modes : 

0 :  Read 
1 :  Write 
2:  Read/Write 

Returns  -1  if  file  was  not  opened, 
otherwise  returns  file  handle. 


cProc 

parmDP 

parmB 

cBegin 


op_ok : 
cEnd 


open, PUBLIC, ds 

pfilepath 

mode 


loadDP 

mov 

mov 

int 

jnb 

mov 


ds,dx, pfilepath  ;  Get  pointer  to  pathname. 
al,mode  ;  Get  read/write  mode, 

ah, 3dh  ;  Request  MS-DOS  to  open  the 

21 h  ;  existing  file. 

op_ok  ;  Branch  if  MS-DOS  returned  handle. 

ax,-l  ;  Else  return  -1. 
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Interrupt  21H  (33)  2.0  and  later 

Function  3EH  (62) 

Close  File 


Function  3EH  closes  the  file  referenced  by  the  specified  handle. 

ToCaU 

AH  =  3EH 

BX  =  handle  number 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

06H  invalid  handle  number 

Programmer’s  Notes 

•  The  handle  in  BX  must  be  one  that  was  returned  by  a  successful  call  to  one  of  the 
following  functions: 

-  3CH  (Create  File  with  Handle) 

-  3DH  (Open  File  with  Handle) 

-  5AH  (Create  Temporary  File) 

-  5BH  (Create  New  File) 

•  If  the  file  has  been  modified,  truncated,  or  extended.  Function  3EH  updates  the  cur¬ 
rent  date,  time,  and  file  size  in  the  directory  entry. 

•  All  internal  MS-DOS  buffers  for  the  file,  including  directory  and  file  allocation  table 
(FAT)  buffers,  are  flushed  to  disk. 

•  With  MS-DOS  versions  3.0  and  later,  a  program  must  remove  all  file  locks  in  effect 
before  it  closes  a  file.  The  result  of  closing  a  file  with  active  locks  is  unpredictable. 

•  Function  59H  ((jet  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 
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Related  Functions 

lOH  (Close  File  with  FCB) 

3CH  (Create  File  with  Handle) 
3DH  (Open  File  with  Handle) 
5AH  (Create  Temporary  File) 
5BH  (Create  New  File) 

Example 


Function  3EH:  Close  File 


int  close (handle) 
int  handle; 

Returns  -1  if  file  was  not  closed, 
otherwise  returns  0. 


cProc 

close. 

PUBLIC 

parmW 

handle 

cBegin 

mov 

bx, handle 

;  Get  handle. 

mov 

ah, 3eh 

;  Set  function  codes. 

int 

21h 

;  Ask  MS-DOS  to  close  handle 

mov 

al,0 

jnb 

cl_ok 

;  Branch  if  no  error. 

mov 

al,-1 

;  Else  return  -1 . 

cl_ok: 

cbw 

;  Extend  result . 

cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  3FH  (63) 

Read  File  or  Device 


Function  3FH  reads  from  the  file  or  device  referenced  by  a  handle. 

ToCaU 


AH 

=  3FH 

BX 

=  handle  number 

CX 

=  number  of  bytes  to  read 

DS:DX 

=  segment:offset  of  data  buffer 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX 

=  number  of  bytes  read  from  file 

DS:DX 

=  segment:offset  of  data  read  from  file 

If  function  is  not  successful: 


Carry  flag  is  set. 

AX  =  error  code: 

05H  access  denied 

06H  invalid  handle 

Programmer's  Notes 

•  Data  is  read  from  the  file  beginning  at  the  current  location  of  the  file  pointer.  After  a 
successful  read,  the  file  pointer  is  updated  to  point  to  the  byte  following  the  last  byte 
read. 

•  If  Function  3FH  returns  OOH  in  the  AX  register,  the  function  attempted  to  read  when 
the  file  pointer  was  at  the  end  of  the  file.  If  AX  is  less  than  CX,  a  partial  record  at  the 
end  of  the  file  was  read. 

•  Function  3FH  can  be  used  with  all  handles,  including  standard  input  (normally  the 
keyboard).  When  reading  from  standard  input,  this  function  normally  reads  charac¬ 
ters  only  to  the  first  carriage-return  character.  Thus,  the  number  of  bytes  read  in  AX 
will  not  necessarily  match  the  length  requested  in  CX. 

•  On  networks  running  under  MS-DOS  version  3.1  or  later,  the  user  must  have  Read 
access  to  the  directory  and  file  containing  the  information  to  be  read. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 
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Related  Functions 

40H  (Write  File  or  Device) 

42H  (Move  File  Pointer) 

59H  (Get  Extended  Error  Information) 

Example 

.*********♦********♦  *****4e**************s|c*!|e**s|c***  ************ 

;  Function  3FH:  Read  File  or  Device 

9 

;  int  read (handle, pbuffer,nbytes) 

;  int  handle, nbytes; 

;  char  *pbuffer; 

/ 

;  '  Returns  -1  if  there  was  a  read  error, 

;  otherwise  returns  number  of  bytes  read. 

/ 

.************************************************************ 


cProc 

read, PUBLIC, ds 

parmW 

handle 

parmDP 

pbuf fer 

parmW 

nbytes 

cBegin 

mov 

bx, handle 

;  Get  handle . 

loadDP 

ds, dx,pbuffer 

;  Get  pointer  to  buffer. 

mov 

cx, nbytes 

;  Get  number  of  bytes  to  read 

mov 

ah,3fh 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  to  read  CX  bytes 

jnb 

rd_ok 

;  Branch  if  read  worked. 

mov 

ax,  -1 

;  Else  return  -1 . 

rd_ok: 

cEnd 
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2111  (33)  2.0  and  later 

Function  40H  (64) 

Write  File  or  Device 


Function  40H  writes  the  specified  number  of  bytes  to  a  file  or  device  referenced  by  a 

handle. 

ToCaU 

AH  =40H 

BX  =  handle 

CX  =  number  of  bytes  to  write 

DS:DX  =  segment:offset  of  data  buffer 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX  =  number  of  bytes  written  to  file  or  device 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OSH  access  denied 

06H  invalid  handle 

Programmer’s  Notes 

•  Data  is  written  to  the  file  or  device  beginning  at  the  current  location  of  the  file 
pointer.  After  writing  the  specified  data,  Function  40H  updates  the  position  of  the 
file  pointer  and  returns  the  actual  number  of  bytes  written  in  AX. 

•  Function  40H  returns  error  code  OSH  (access  denied)  if  the  file  was  opened  as  read¬ 
only  with  Function  3CH  (Create  File  with  Handle),  3DH  (Open  File  with  Handle), 

SAH  (Create  Temporary  File),  or  SBH  (Create  New  File).  On  networks  running  under 
MS-DOS  version  3.1  or  later,  access  is  also  denied  if  the  file  or  record  has  been  locked 
by  another  process. 

•  The  handle  number  in  BX  must  be  one  of  the  predefined  device  handles  (0  through  4) 
or  a  handle  obtained  through  a  previous  call  to  open  or  create  a  file  (such  as  Function 
3CH,  3DH,  SAH,  or  SBH). 

•  If  CX  =  0,  the  file  is  truncated  or  extended  to  the  current  file  pointer  location.  Clusters 
are  allocated  or  released  in  the  file  allocation  table  (FAT)  as  required  to  fulfill  the 
request. 
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•  If  the  handle  parameter  for  Function  40H  refers  to  a  disk  file  and  the  number  of  bytes 
written  (returned  in  AX)  is  less  than  the  number  requested  in  CX,  the  destination  disk 
is  full.  The  carry  flag  is  not  set  in  this  situation. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

3FH  (Read  File  or  Device) 

42H  (Move  File  Pointer) 

Example 

;  Function  40H:  Write  File  or  Device  ; 

;  int  write (handle, pbuffer,nbytes)  ; 

;  int  handle, nbytes;  ; 

;  char  *pbuffer;  ; 

;  Returns  -1  if  there  was  a  write  error,  ; 

;  otherwise  returns  number  of  bytes  written.  ; 

.4:*4c4:****«*4c:)<***4:*4:********4c4!***4:!ic*4c%4::|c:ici|c4c9|c*Hc*****9Kiic***:)ci|c«***; 

cProc  write, PUBLIC, ds 
parmW  handle 
parmDP  pbuffer 
parmW  nbytes 
cBegin 


mov 

bx, handle 

/  Get  handle . 

loadDP 

ds, dx, pbuffer 

;  Get  pointer  to  buffer. 

mov 

CX, nbytes 

;  Get  number  of  bytes  to  write 

mov 

ah,40h 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  to  write  CX  bytes 

jnb 

wr_ok 

;  Branch  if  write  successful. 

mov 

ax,  -1 

;  Else  return  -1 . 

wr_ok : 

cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  41H  (65) 

Delete  File 


Function  4lH  deletes  the  directory  entry  of  the  specified  file. 

ToCaU 

AH  =  41H 

DS:DX  =  segmentioffset  of  ASCIIZ  pathname 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

02H  file  not  found 

03H  path  not  found 

05H  access  denied 

Programmer’s  Notes 

•  The  pathname  must  be  a  null-terminated  ASCII  string  (ASCIIZ).  Unlike  Function  13H 
(Delete  File),  Function  41H  does  not  allow  wildcard  characters  in  the  pathname. 

•  Because  Function  41H  supports  the  use  of  full  pathnames,  it  is  preferable  to  Function 
13H. 

•  Function  41H  returns  error  code  05H  (access  denied)  and  fails  if  the  file  has  either  a 
directory  or  volume  attribute  or  if  it  is  a  read-only  file. 

A  directory  can  be  deleted  (if  it  is  empty)  with  Function  3AH  (Remove  Directory).  A 
read-only  file  can  be  deleted  if  its  attribute  is  changed  to  normal  with  Function  43H 
(Get/Set  File  Attributes)  before  Function  41H  is  called. 

•  On  networks  running  under  MS-DOS  version  3.1  or  later,  the  user  must  have  Create 
access  to  the  directory  containing  the  file  to  be  deleted. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

3AH  (Remove  Directory) 

43H  (Get/Set  File  Attributes) 
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Example 


;  Function  41 H:  Delete  File 

# 

;  int  delete (pfilepath) 

;  char  *pfilepath; 

;  Returns  0  if  file  deleted, 

;  otherwise  returns  error  code. 

/ 

«3(e:ic3|c4e:fe:lc9ie:fe)|e9|c«4e4c:|e**%3|c*****3ie3|e*3|e*4e4e9|e4e4e3|c4e*4e:|e4e4e4c4:4:3|e3ic)|e4e3|e:|e9|e:|e3|c:|c>|e:|c4G4c4e:ic% 

cProc  delete, PUBLIC, ds 
paritiDP  pfilepath 
cBegin 

loadDP 
mov 
int 
jb 

xor 

dl_err ; 
cEnd 


ds, dx, pfilepath 

ah,41h 

21h 

dl_err 

ax,  ax 


Get  pointer  to  pathname. 

Set  function  code. 

Ask  MS-DOS  to  delete  file. 

Branch  if  MS-DOS  could  not  delete 
file. 

Else  return  0. 
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Interrupt  21H  (33)  2.0  and  later 

Function  42H  (66) 

Move  File  Pointer 


Function  42H  sets  the  position  of  the  file  pointer  (for  the  next  read/write  operation)  for 
the  file  associated  with  the  specified  handle. 

ToCaU 

AH  =  42H 

AL  =  method  code: 

OOH  byte  offset  from  beginning  of  file 

OlH  byte  offset  from  current  location  of  file  pointer 
02H  byte  offset  from  end  of  file 
BX  =  handle  number 

CX:DX  =  offset  value  to  move  pointer: 

CX  most  significant  half  of  a  doubleword  value 
DX  least  significant  half  of  a  doubleword  value 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

DX:AX  =  new  file  pointer  position  (absolute  byte  offset  from  beginning  of  file) 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function  (AL  not  OOH,  OlH,  or  02H) 

06H  invalid  handle 

Programmer’s  Notes 

•  The  value  in  CX:DX  is  an  offset  specifying  how  far  the  file  pointer  is  to  be  moved. 

With  method  code  OOH,  the  value  in  CX:DX  is  always  interpreted  as  a  positive  32-bit 
integer,  meaning  the  file  pointer  is  always  set  relative  to  the  beginning  of  the  file. 

With  method  codes  OlH  and  02H,  the  value  in  CX:DX  can  be  either  a  positive  or  nega¬ 
tive  32-bit  integer.  Thus,  method  1  can  move  the  file  pointer  either  forward  or  back¬ 
ward  from  its  current  position;  method  2  can  move  the  file  pointer  either  forward  or 
backward  from  the  end  of  the  file. 
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•  Specifying  method  code  OOH  with  an  offset  of  0  positions  the  file  pointer  at  the  begin¬ 
ning  of  the  file.  Similarly,  specifying  method  code  02H  with  an  offeet  of  0  conve¬ 
niently  positions  the  file  pointer  at  the  end  of  the  file.  With  method  code  02H  offset  0, 
the  size  of  the  file  can  also  be  determined  by  examining  the  pointer  position  returned 
by  the  function. 

•  Depending  on  the  offset  specified  in  CX:DX,  methods  1  and  2  may  move  the  file 
pointer  to  a  position  before  the  start  of  the  file.  Function  42H  does  not  return  an  error 
code  if  this  happens,  but  later  attempts  to  read  from  or  write  to  the  file  will  produce 
unexpected  errors. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

3FH  (Read  File  or  Device) 

40H  (Write  File  or  Device) 

Example 

.«*«*4::{c4c******4c*«*Hc***:|c*!ic«****«*!|c**«*****4:***Hc*«*«*********Hc4c; 

;  Function  42H:  Move  File  Pointer  ; 

;  long  seek (handle, distance, mode)  ; 

;  int  handle, mode;  ; 

;  long  distance;  ; 

;  Modes :  ; 

;  0:  from  beginning  of  file  ; 

;  1 :  from  the  current  position  ; 

;  2:  from  the  end  of  the  file  ; 

;  Returns  -1  if  there  was  a  seek  error,  ; 

;  otherwise  returns  long  pointer  position.  ; 

.*************************♦♦♦♦*****♦*************************; 


cProc 

seek, PUBLIC 

parmW 

handle 

parmD 

distance 

parmB 

mode 

cBegin 

mov 

bx, handle 

;  Get 

handle. 

les 

dx, distance 

;  Get 

distance  into  ES:DX. 

mov 

cx,  es 

;  Put 

high  word  of  distance  into  CX 

mov 

a 1, mode 

;  Get 

move  method  code. 

mov 

ah,42h 

;  Set 

function  code. 

(more) 
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int  21  h 

jnb  sk_ok 

mov  ax,-1 

cwd 

sk_ok: 

cEnd 


;  Ask  MS-DOS  to  move  file  pointer. 
;  Branch  if  seek  successful. 

;  Else  return  -1 . 
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Interrupt  21H  (33)  2.0  and  later 

Function  43H  (67) 

Get/Set  File  Attributes 


Function  43H  gets  or  sets  the  attributes  of  the  specified  file. 

ToCaU 

AH  =  43H 

To  get  file  attributes: 

AL  =  OOH 

DS:DX  =  segment:offset  of  ASCIIZ  pathname 

To  set  file  attributes: 

AL  =  OlH 

CX  =  attributes  to  set: 


Bit  Attribute 

0  Read-only  file 

1  Hidden  file 

2  System  file 

5  Archive 

DS:DX  =  segment:offset  of  ASCIIZ  pathname 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

CX  =  attribute 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function  (AL  not  OOH  or  OlH) 

02H  file  not  found 

03H  path  not  found 

05H  access  denied 
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Programmer’s  Notes 

•  The  pathname  must  be  a  null-terminated  ASCII  string  (ASCIIZ). 

•  Function  43H  cannot  be  used  to  set  or  change  either  a  volume-label  or  directory  at¬ 
tribute  (bits  3  and  4  of  the  attribute  byte).  With  MS-DOS  versions  3.x,  Function  43H 
can  be  used  to  make  a  directory  hidden  or  read-only. 

•  On  networks  running  under  MS-DOS  version  3.1  or  later,  the  user  must  have  Create 
access  to  the  directory  containing  the  file  in  order  to  change  the  read-only,  hidden,  or 
system  attribute.  The  archive  bit,  however,  can  be  changed  regardless  of  access  rights. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 
None 
Example 

.4c*«****3|‘*«4c**9|c4:********«***:ic3|c***«*4c********************>t:*9tc4c*; 

;  Function  43H:  Get/Set  File  Attributes  / 

;  int  file_attr (pfilepath, func, attr)  ; 

;  char  *pfilepath;  ; 

;  int  func,attr;  ; 

;  Returns  -1  for  all  errors,  ; 

;  otherwise  returns  file  attribute.  ; 

.*4c*******«9ic************4(4e*’ic***4(*4c*«********************«He*:)c*; 

cProc  file_attr, PUBLIC, ds 
parmDP  pfilepath 
parmB  func 
parmW  attr 
cBegin 

loadDP 
mov 
mov 
mov 
int 
jnb 
mov 

fa_ok: 

mov  ax,cx  ;  Return  this  value. 

cEnd 


ds,dx, pfilepath 
al, func 
cx, attr 
ah, 43h 


Get  pointer  to  pathname. 
Get /set  flag  into  AL. 

Get  new  attr  (if  present) 
Set  code  function. 

Call  MS-DOS. 

Branch  if  no  error. 

Else  return  -1 . 
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Interrupt  21H  (33)  2  0  and  later 

Function  44H  (68) 

lOCTL 


Function  44H  is  a  collection  of  subfunctions  that  provide  a  process  a  direct  path  of  com¬ 
munication  with  a  device  driver.  As  such,  this  function  is  the  most  flexible  means  of  gain¬ 
ing  access  to  the  full  capabilities  of  an  installed  device. 

An  lOCTL  subfunction  is  called  with  44H  in  AH  and  the  value  for  the  subfunction  in  AL.  If 
a  subfunction  has  minor  functions,  those  values  are  specified  in  CL.  Otherwise,  the  BX, 
CX,  and  DX  registers  are  used  for  such  information  as  handles,  drive  identifiers,  buffer  ad¬ 
dresses,  and  so  on. 

The  subfunctions  and  the  versions  of  MS-DOS  with  which  they  are  available  are 


MS-DOS 


Subfiinction 

Name 

Versions 

OOH 

Get  Device  Data 

2.0  and  later 

OlH 

Set  Device  Data 

2.0  and  later 

02H 

Receive  Control  Data  from  Character  Device 

2.0  and  later 

03H 

Send  Control  Data  to  Character  Device 

2.0  and  later 

04H 

Receive  Control  Data  from  Block  Device 

2.0  and  later 

05H 

Send  Control  Data  to  Block  Device 

2.0  and  later 

O6H 

Check  Input  Status 

2.0  and  later 

07H 

Check  Output  Status 

2.0  and  later 

OSH 

Check  If  Block  Device  Is  Removable 

3.0  and  later 

09H 

Check  If  Block  Device  Is  Remote 

3.1  and  later 

OAH 

Check  If  Handle  Is  Remote 

3.1  and  later 

OBH 

Change  Sharing  Retry  Count 

3.1  and  later 

OCH 

(Generic  I/O  Control  for  Handles 

Minor  Code  45H:  Set  Iteration  Count 

Minor  Code  65H:  Get  Iteration  Count 

3.2 

ODH 

Generic  I/O  Control  for  Block  Devices 

Minor  Code  40H:  Set  Device  Parameters 

Minor  Code  6OH:  Get  Device  Parameters 

Minor  Code  4lH:  Write  Track  on  Logical  Drive 
Minor  Code  6IH:  Read  Track  on  Logical  Drive 
Minor  Code  42H:  Format  and  Verify  Track 
on  Logical  Drive 

Minor  Code  62H:  Verify  Track  on  Logical  Drive 

3.2 

(more) 


Section  V:  System  Calls  1317 


Interrupt  21H  Function  44H 


MS-DOS 

Subfunction  Name  Versions 

OEH  Get  Logical  Drive  Map  3.2 

OFH  Set  Logical  Drive  Map  3.2 

These  subfunctions  are  documented,  either  individually  or  in  related  pairs,  in  the  entries 
that  follow. 
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Interrupt  21H  (33)  2.0  and  later 

Function  44H  (68)  Subfunction  OOH 

lOCTL:  Get  Device  Data 


Function  44H  Subfunction  OOH  gets  information  about  a  character  device  or  file  referenced 
by  a  handle. 

ToCaU 

AH  =44H 
AL  =00H 

BX  =  handle  number 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

DX  contains  information  on  file  or  device: 


Bit 

Value 

Meaning 

For  a  file  (bit  7  =  0): 

8-15 

0 

Reserved. 

7 

0 

Handle  refers  to  a  file. 

6 

0 

File  has  been  written. 

0-5 

Drive  number  (0  =  A,  1  =  B,  2  =  C,  and  so  on). 

For  a  device  (bit  7  =  1): 


15  0 

14  1 


8-13  0 

7  1 

6  0 

5  0 

1 


Reserved. 

Processes  control  strings  transferred  by  lOCTL  Subfunctions  02H 
(Receive  Control  Data  from  Character  Device)  and  03H  (Send 
Control  Data  to  Character  Device),  set  by  MS-DOS. 

Reserved. 

Handle  refers  to  a  device. 

End  of  file  on  input. 

Checks  for  control  characters  (cooked  mode). 

Does  not  check  for  control  characters  (raw  mode). 


(more) 
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Bit  Value  Meaning 


4 

3 

2 

1 

0 


0 

1 

1 

1 

1 


Reserved. 

Clock  device. 

Null  device. 

Standard  output  device. 
Standard  input  device. 


If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  lOCTL  subfunction 

05H  access  denied 

06H  invalid  handle 

Programmer’s  Notes 

•  Bits  8-15  of  DX  correspond  to  the  upper  8  bits  of  the  device-driver  attribute  word. 

•  The  handle  in  BX  must  reference  an  open  device  or  file. 

•  Bit  5  of  the  device  data  word  for  character-device  handles  defines  whether  that  han¬ 
dle  is  in  raw  mode  or  cooked  mode.  In  cooked  mode,  MS-DOS  checks  for  Control-C, 
Control-P,  Control-S,  and  Control-Z  characters  and  transfers  control  to  the  Control-C 
exception  handler  (whose  address  is  saved  in  the  vector  for  Interrupt  23H)  when  a 
Control-C  is  detected.  In  raw  mode,  MS-DOS  does  not  check  for  such  characters  when 
I/O  is  performed  to  the  handle;  however,  it  will  still  check  for  a  Control-C  entered  at 
the  keyboard  on  other  function  calls  unless  such  checking  has  been  turned  off  with 
Function  33H,  the  BREAK=OFF  directive  in  CONFIG.SYS,  or  a  BREAK  OFF  com¬ 
mand  at  the  MS-DOS  prompt. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

33H  (Get/Set  Control-C  Check  Flag) 

3CH  (Create  File  with  Handle) 

3DH  (Open  File  with  Handle) 
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Example 

f*******^*^i::¥*******************************iti**t**.**^********* 

r 

;  Function  44H,  Subfunctions  OOH, 01 H: 

;  Get/Set  lOCTL  Device  Data 

;  int  ioctl_char_flags (setf lag, handle, newf lags) 

;  int  setflag; 

;  int  handle; 

;  int  newf lags; 

/ 

;  Set  setflag  =  0  to  get  flags,  1  to  set  flags. 

;  Returns  -1  for  error,  else  returns  flags. 

/ 


cProc 

ioctl_char_f lags, PUBLIC 

parmB 

setflag 

parmW 

handle 

parmW 

newf lags 

cBegin 

mov 

al, setflag 

Get  setflag. 

and 

al,1 

Save  only  Isb. 

mov 

bx, handle 

Get  handle  to  character 

device . 

mov 

dx, newf lags 

Get  new  flags  (they  are 
by  "set”  option) . 

used  only 

mov 

ah,44h 

Set  function  code. 

int 

21h 

Call  MS-DOS. 

mov 

ax,  dx 

Assume  success  -  prepare  to  return 

flags . 

jnc 

iocfx 

Branch  if  no  error. 

mov 

ax,  -1 

Else  return  error  flag. 

iocfx; 

cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  44H  (68)  Subfunction  OlH 

lOCTL:  Set  Device  Data 


Function  44H  Subfunction  OlH,  the  complement  of  lOCTL  Subfunction  OOH,  sets  informa¬ 
tion  about  a  character  device — but  not  a  file — referenced  by  a  handle. 

ToCaU 

AH  =  44H 
AL  =  OlH 

BX  =  handle  number 
DX  =  device  data  word: 


Bit  Value  Meaning 

8-15  0 

7  1 

6  0 

5  0 

1 

4  0 

3  1 

2  1 

1  1 

0  1 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  lOCTL  subfunction 

05H  access  denied 

06H  invalid  handle 


Reserved. 

Handle  refers  to  a  device. 

End  of  file  on  input. 

Check  for  control  characters 
(cooked  mode). 

Do  not  check  for  control  characters 
(raw  mode). 

Reserved. 

Clock  device. 

Null  device. 

Standard  output  device. 

Standard  input  device. 
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Programmer’s  Notes 

•  The  handle  in  BX  must  reference  an  open  device. 

•  DH  must  be  OOH.  If  it  is  not,  the  carry  flag  is  set  and  error  code  OlH  (invalid  function) 
is  returned. 

•  Bit  5  of  the  device  data  word  for  character-device  handles  selects  raw  mode  or  cooked 
mode  for  the  handle.  In  cooked  mode,  MS-DOS  checks  for  Control-C,  Control-P, 
Control-S,  and  Control-Z  characters  and  transfers  control  to  the  Control-C  exception 
handler  (whose  address  is  saved  in  the  vector  for  Interrupt  23H)  when  a  Control-C  is 
detected.  In  raw  mode,  MS-DOS  does  not  check  for  such  characters  when  I/O  is  per¬ 
formed  to  the  handle;  however,  it  will  still  check  for  a  Control-C  entered  at  the  key¬ 
board  on  other  function  calls  unless  such  checking  has  been  turned  off  with  Function 
33H,  the  BREAK=OFF  directive  in  CONFIG.SYS,  or  a  BREAK  OFF  command  at  the 
MS-DOS  prompt. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

33H  (Get/Set  Control-C  Check  Flag) 

3CH  (Create  File  with  Handle) 

3DH  (Open  File  with  Handle) 

Example 

See  SYSTEM  CALLS:  Interrupt  21h:  Function  44H  Subfunction  OOH. 
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Interrupt  21H  (33)  2.0  and  later 

Function  44H  (68)  Subfunctions  02H  and  03H 

lOCTL:  Receive  Control  Data  from  Character  Device;  Send  Control  Data  to 
Character  Device 


Function  44H  Subfunctions  02H  and  03H  respectively  receive  and  send  control  strings 
from  and  to  a  character-oriented  device  driver. 

ToCaU 

AH  =  44H 

AL  =  02H  receive  control  strings 

03H  send  control  strings 

BX  =  handle  number 

CK  =  number  of  bytes  to  transfer 

DS:DX  =  segment:offset  of  data  buffer 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX  =  number  of  bytes  transferred 

If  AL  was  02H  on  call: 

Buffer  atpS:DX  contains  data  read  from  device  driver. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

05H  access  denied 

06H  invalid  handle 

ODH  invalid  data  (bad  control  string) 

Programmer’s  Notes 

•  Subfunctions  02H  and  03H  provide  a  means  of  transferring  control  information  of  any 
type  or  length  between  an  application  program  and  a  character-device  driver.  They 
do  not  necessarily  result  in  any  input  to  or  output  from  the  physical  device  itself. 

•  Subfunction  02H  can  be  used  to  read  control  information  about  such  features  as 
device  status,  availability,  and  current  output  location.  Subfunction  03H  is  often  used 
to  configure  the  driver  or  device  for  subsequent  I/O;  for  example,  it  may  be  used  to  set 
the  baud  rate,  word  length,  and  parity  for  a  serial  communications  adapter  or  to  initial¬ 
ize  a  printer  for  a  specific  font,  page  length,  and  so  on.  The  format  of  the  control  data 
passed  by  these  subfunctions  is  driver  specific  and  does  not  follow  any  standard. 
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•  Character-device  drivers  are  not  required  to  support  lOCTL  Subfunctions  02H  and 
03H.  Therefore,  Subfunction  OOH  (Get  Device  Data)  should  be  called  before  either 
Subfunction  02H  or  03H  to  determine  whether  a  device  can  process  control  strings. 

If  bit  14  of  the  device  data  word  returned  by  Subfunction  OOH  is  set,  the  device  driver 
supports  lOCTL  Subfunctions  02H  and  03H. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 


44H  Subfunction  OOH  (Get  Device  Data) 

44H  Subfunction  04H  (Receive  Control  Data  from  Block  Device) 
44H  Subfunction  05H  (Send  Control  Data  to  Block  Device) 

Example 


Function  44H,  Subfunctions  02H,03H: 

lOCTL  Character  Device  Control 

int  ioct l_char_ct rl ( recvf lag, handle , pbuf f er , nbytes ) 
int  recvflag; 
int  handle; 
char  *pbuffer; 
int  nbytes; 

Set  recvflag  =  0  to  receive  info,  1  to  send. 

Returns  -1  for  error,  otherwise  returns  number  of 
bytes  sent  or  received. 


cProc 

parmB 

parmW 

parmDP 

parmW 

cBegin 


iccx: 

cEnd 


ioct l_char_ctrl, PUBLIC, <ds> 

recvflag 

handle 

pbuf fer 

nbytes 


mov 

al, recvflag 

;  Get  recvflag. 

and 

al,  1 

;  Keep  only  Isb. 

add 

al,2 

;  AL  =  02H  for  receive,  03H  for  send. 

mov 

bx, handle 

;  Get  character-device  handle. 

mov 

cx, nbytes 

;  Get  number  of  bytes  to  receive/send 

loadDP 

ds, dx, pbuf fer 

;  Get  pointer  to  buffer. 

mov 

ah,44h 

;  Set  function  code. 

int 

21h 

;  Call  MS-DOS. 

jnc 

iccx 

;  Branch  if  no  error. 

mov 

ax,  -1 

;  Return  -1  for  all  errors. 
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Interrupt  21H  (33)  2.0  and  later 

Function  44H  (68)  Subfunctions  04H  and  05H 

lOCTL:  Receive  Control  Data  from  Block  Device;  Senci  Control  Data  to  Block 
Device 


Function  44H  Subfunctions  04H  and  05H  respectively  receive  and  send  control  strings 
from  and  to  a  block-oriented  device  driver. 

To  Call 

AH  =44H 

AL  =  04H  receive  block-device  data 

05H  send  block-device  data 

BL  =  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 

CX  =  number  of  bytes  to  transfer 

DS:DX  =  segment:offset  of  data  buffer 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX  =  number  of  bytes  transferred 

If  AL  was  04H  on  call: 

Buffer  at  DS:DX  contains  control  data  read  from  device  driver. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

05H  access  denied 

06H  invalid  handle 

ODH  invalid  data  (bad  control  string) 

Programmer’s  Notes 

•  Subfunctions  04H  and  05H  provide  a  means  of  transferring  control  information  of  any 
type  or  length  between  an  application  program  and  a  block-device  driver.  They  do 
not  necessarily  result  in  any  input  to  or  output  from  the  physical  device  itself. 

•  Control  strings  can  be  used  to  request  driver  operations  that  are  not  file  oriented,  such 
as  tape  rewind  or  disk  eject  (if  hardware  supported).  The  contents  of  such  control 
strings  are  specific  to  individual  device  drivers  and  do  not  follow  any  standard  format. 
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•  Subfunction  04H  can  be  used  to  obtain  a  code  from  the  driver  indicating  device  avail¬ 
ability  or  status.  Block  devices  that  might  use  this  subfunction  include  magnetic  tape 
or  tape  cassette,  CD  ROM,  and  Small  Computer  Standard  Interface  (SCSI)  devices. 

•  Block-device  drivers  are  not  required  to  support  lOCTL  Subfunctions  04H  and  05H.  If 
the  driver  does  not  support  these  subfiinctions,  error  code  OlH  (Invalid  Function)  is 
returned. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error— in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

44H  Subfunction  OOH  (Get  Device  Data) 

44H  Subfunction  02H  (Receive  Control  Data  from  Character  Device) 

44H  Subfunction  03H  (Send  Control  Data  to  Character  Device) 

Example 

f********H!***:it4fi**********************4^*^!¥**iit*****************‘ 

;  Function  44H,  Subfunctions  04H, OSH:  ; 

;  lOCTL  Block  Device  Control  ; 

;  int  ioctl_block_ctrl (recvflag,drive_ltr,pbuffer,nbytes)  ; 

;  int  recvflag;  ; 

;  int  drive_ltr;  ; 

;  char  *pbuffer;  ; 

;  int  nbytes;  ; 

;  Set  recvflag  =  0  to  receive  info,  1  to  send.  ; 

;  Returns  -1  for  error,  otherwise  returns  number  of  ; 

;  bytes  sent  or  received.  ; 

cProc  ioctl_block_ctrl, PUBLIC, <ds> 
parmB  recvflag 
parmB  drive_ltr 
parmDP  pbuffer 
parmW  nbytes 
cBegin 

mov 
and 
add 
mov 
or 

jz 

and 
sub 

;  'B'  =2,  etc. 


al, recvflag 

al,1 

al,4 

bl,  drive_ltr 

bl,bl 

ibc 

bl,not  20h 
bl,  'A'-1 


Get  recvflag. 

Keep  only  Isb. 

AL  =  04H  for  receive. 
Get  drive  letter. 
Leave  0  alone. 


OSH  for  send. 


Convert  letter  to  uppercase. 
Convert  to  drive  number:  'A' 


1, 


(more) 
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ibc; 

mov 

cx, nbytes 

Get  number  of  bytes  to  reeeive/send 

loadDP 

ds, dx, pbuf fer 

r 

Get  pointer  to  buffer. 

mov 

ah,44h 

; 

Set  funetion  eode. 

int 

21h 

/ 

Call  MS-DOS. 

jnc 

ibex 

f 

Braneh  if  no  error. 

mov 

ax,  -1 

f 

Return  -1  for  all  errors. 

ibex: 

cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  44H  (68)  Subfunctions  06H  and  07H 

lOCTL:  Check  Input  Status;  Check  Output  Status 


Function  44H  Subfunctions  06H  and  07H  respectively  determine  whether  a  device  or  file 
associated  with  a  handle  is  ready  for  input  or  output. 

ToCaU 

AH  =  44H 

AL  =  06H  get  input  status 
07H  get  output  status 
BX  =  handle  number 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AL  =  input  or  output  status: 

OOH  not  ready 
FFH  ready 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

05H  access  denied 

06H  invalid  handle 

ODH  invalid  data  (bad  control  string) 

Programmer’s  Notes 

•  The  status  returned  in  AL  has  the  following  meanings: 


Status  Device  Input  File  Output  File 

OOH  Not  ready  Pointer  at  EOF  Ready 

OFFH  Ready  Ready  Ready 
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•  Output  files  always  return  a  ready  condition,  even  if  the  disk  is  full  or  no  disk  is  in  the 
drive. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 
None 
Example 


;tiilliit‘*^******ilH^**^******************************************** 

Function  44H,  Subfunctions  06H,07H: 

lOCTL  Input/Output  Status 

int  ioctl_char_status (output flag, handle) 
int  outputflag; 
int  handle; 

Set  outputflag  =  0  for  input  status,  1  for  output  status. 

Returns  -1  for  all  errors,  0  for  not  ready, 
and  1  for  ready. 


cProc  ioctl_char_status,  PUBLIC 
parmB  outputflag 
parmW  handle 
cBegin 


isnoerr ; 


mov 

al, outputflag 

f 

Get  outputflag. 

and 

al,1 

; 

Keep  only  Isb. 

add 

al,6 

; 

AL  =  06H  for  input  status,  07H  for  output 

; 

status. 

mov 

bx, handle 

; 

Get  handle. 

mov 

ah, 44h 

; 

Set  function  code. 

int 

21h 

; 

Call  MS-DOS. 

jnc 

isnoerr 

; 

Branch  if  no  error. 

mov 

ax,  -1 

; 

Return  error  code. 

jmp 

short  isx 

and 

ax,  1 

; 

Keep  only  Isb  for  return  value. 

isx; 

cEnd 
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Interrupt  21H  (33)  3.0  and  later 

Function  44H  (68)  Subfunction  OSH 

lOCTL:  Check  If  Block  Device  Is  Removable 


Function  44H  Subfunction  OSH  checks  whether  the  specified  block  device  contains  a 
removable  storage  medium,  such  as  a  floppy  disk. 

To  CaU 

AH  =44H 
AL  =  OSH 

BL  =  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX  =00H  storage  medium  removable 

OlH  storage  medium  not  removable 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

OFH  invalid  drive 

Programmer’s  Notes 

•  This  subfunction  exists  to  allow  an  application  to  check  for  a  removable  disk  so  that 
the  user  can  be  prompted  to  change  disks  if  a  required  file  is  not  found. 

•  When  the  carry  flag  is  set,  error  code  OlH  normally  means  that  MS-DOS  did  not  recog¬ 
nize  the  function  call.  However,  this  error  can  also  mean  that  the  device  driver  does 
not  support  Subfunction  OSH.  In  this  case,  MS-DOS  assumes  that  the  storage  medium 
is  not  removable. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

None 
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Example 

;  Function  44H,  Subfunction  OSH: 

;  lOCTL  Removable  Block  Device  Query 

;  int  ioctl_block_fixed (drive_ltr) 

;  int  drive_ltr; 

;  Returns  -1  for  all  errors,  1  if  disk  is  fixed  (not 

;  removable) ,  0  if  disk  is  not  fixed. 

jHH^Uft^llli^lllt^f****************************************************** 


cProc  ioctl_block_fixed, PUBLIC 

parmB  drive_ltr 

cBegin 

mov  bl,drive_ltr 

or  bl,bl 

jz  ibch 

and  bl,not  20h 

sub  bl, 'A' -1 

ibch: 

mov  ax,4408h 

int  21h 

jnc  ibchx 

cmp  ax, 1 

je  ibchx 

mov  ax,-1 

ibchx : 
cEnd 


Get  drive  letter. 

Leave  0  alone. 

Convert  letter  to  uppercase. 

Convert  to  drive  number:  ’A'  =  1, 
'B'  =  2,  etc. 

Set  function  code.  Subfunction  OSH. 
Call  MS-DOS. 

Branch  if  no  error,  AX  =  0  or  1 . 
Treat  error  code  of  1  as  "disk  is 
fixed. ” 

Return  -1  for  other  errors. 
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Interrupt  21H  (33)  3.1  and  later 

Function  44H  (68)  Subfunction  09H 

lOCTL:  Check  If  Block  Device  Is  Remote 


Function  44H  Subfunction  09H  checks  whether  the  specified  block  device  is  local 
(attached  to  the  computer  running  the  program)  or  remote  (redirected  to  a  network 
server). 

ToCaU 

AH  =44H 
AL  =09H 

BL  =  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

DX  =  device  attribute  word: 

bit  12  =  1  drive  is  remote 

bit  12  =  0  drive  is  local 

If  function  is  not  successful: 

Carry  flag  is  set, 

AX  =  error  code: 

OlH  invalid  function 

OFH  invalid  drive 

Programmer’s  Notes 

•  This  subfunction  should  be  avoided.  Application  programs  should  not  distinguish  be¬ 
tween  files  on  local  and  remote  devices. 

•  When  the  carry  flag  is  set,  error  code  OlH  can  mean  either  that  the  function  number  is 
invalid  or  that  the  network  has  not  been  started. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

None 
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Example 

;  Function  44H,  Subfunction  09H: 

;  lOCTL  Remote  Block  Device  Query 

;  int  ioctl_block_redir {drive_ltr) 

;  int  drive_ltr; 

;  Returns  -1  for  all  errors,  1  if  disk  is  remote 

;  (redirected),  0  if  disk  is  local. 

.****************♦*♦*♦*************♦***★*♦**♦**************♦* 

cProc  ioctl_block_redir, PUBLIC 


parmB 

drive. 

_ltr 

cBegin 

mov 

bl,drive_ltr 

Get  drive  letter. 

or 

bl,bl 

Leave  0  alone. 

jz 

ibr 

and 

bl,not  20h 

Convert  letter  to  uppercase. 

sub 

bl, 'A'-l 

Convert  to  drive  number:  'A'  =  1, 

'B'  =  2,  etc. 

ibr : 

mov 

ax, 4409h 

Set  function  code.  Subfunction  09H 

int 

21h 

Call  MS-DOS. 

mov 

ax,  -1 

Assume  error. 

jc 

ibrx 

Branch  if  error,  returning  -1 . 

inc 

ax 

Set  AX  =  0. 

test 

dh, lOh 

Is  bit  12  set? 

jz 

ibrx 

If  not,  disk  is  local:  Return  0. 

inc 

ax 

Return  1  for  remote  disk. 

ibrx: 

cEnd 
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Interrupt  21H  (33)  3.1  and  later 

Function  44H  (68)  Subfunction  OAH 

lOCTL:  Check  If  Handle  Is  Remote 


Function  44H  Subfunction  OAH  checks  whether  the  handle  in  BX  refers  to  a  file  or  device 
that  is  local  (on  the  computer  running  the  program)  or  remote  (redirected  to  a  network 
server). 

ToCaU 

AH  =44H 
AL  =0AH 
BX  =  handle 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

DX  =  attribute  word  for  file  or  device: 
bit  15  =  1  remote 

bit  15  =  0  local 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

06H  invalid  handle 

Programmer’s  Notes 

•  Application  programs  should  not  distinguish  between  files  on  local  and  remote 
devices. 

•  When  the  carry  flag  is  set,  error  code  OlH  can  mean  either  that  the  function  number  is 
invalid  or  that  the  network  has  not  been  started. 

Related  Functions 

None 
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Example 


Function  44H,  Subfunction  OAH:  ; 

lOCTL  Remote  Handle  Query  ; 

int  ioctl_char_redir (handle)  ; 

int  handle;  ; 

Returns  -1  for  all  errors,  1  if  device/file  is  remote  ; 
(redirected),  0  if  it  is  local.  ; 

************************************************************* 


cProc  ioctl_char_redir, PUBLIC 

parmW  handle 

cBegin 

mov  bx, handle 
mov  ax,440ah 

int  21 h 

mov  ax,-1 

jc  icrx 

inc  ax 

test  dh,80h 

jz  icrx 

inc  ax 


Get  handle. 

Set  function  code.  Subfunction  OAH 
Call  MS-DOS. 

Assume  error. 

Branch  on  error,  returning  -1 . 

Set  AX  =  0. 

Is  bit  15  set? 

If  not,  device/file  is  local: 
Return  0. 

Return  1  for  remote. 


icrx : 
cEnd 


1336 


The  MS-DOS  Encyclopedia 


Interrupt  21H  Function  44H  Subfiinction  OBH 


Interrupt  21H  (33)  3.1  and  later 

Function  44H  (68)  Subfunction  OBH 

lOCTL:  Change  Sharing  Retry  Count 


Function  44H  Subfunction  OBH  sets  the  number  of  times  MS-DOS  retries  a  disk  operation 

after  a  failure  caused  by  a  file-sharing  violation  before  it  returns  an  error  to  the  requesting 

process. 

ToCaU 

AH  =  44H 

AL  =  OBH 

CX  =  pause  between  retries 

DX  =  number  of  retries 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

Programmer’s  Notes 

•  The  pause  between  retries  is  a  machine-dependent  value  determined  by  the  CPU 
and  CPU  clock  speed.  MS-DOS  performs  a  delay  loop  that  consists  of  65,536  machine 
instructions  for  each  iteration  specified  by  the  value  in  CX.  The  actual  code  is  as 
follows: 

xor  cx,cx 
loop  $ 

The  default  number  of  retries  is  3,  with  a  pause  of  one  loop  between  retries — 
equivalent  to  calling  this  subfiinction  with  DX  =  3  and  CX  =  1. 

•  When  the  carry  flag  is  set,  error  code  OlH  indicates  either  that  the  function  code  is  in¬ 
valid  or  that  file  sharing  (SHARE.EXE)  is  not  loaded. 

•  Subfunction  OBH  can  be  used  to  tune  the  system  if  file-contention  problems  are  likely 
to  arise  with  shared  files  but  are  expected  to  last  only  a  short  while. 

•  If  file  contention  is  expected  and  if  some  applications  will  lock  regions  of  the  file  for 
an  appreciable  period  of  time,  the  user  may  need  to  be  informed.  The  best  procedure 
is  to  set  an  initial  small  number  of  retries  with  a  short  pause  period.  After  notifying 
the  user,  the  application  can  wait  a  reasonable  amount  of  time  for  file  access  by  adjust¬ 
ing  the  retry  or  pause-period  values. 
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•  If  a  process  uses  this  subfiinction,  it  should  restore  the  original  default  values  for  the 
pause  and  number  of  retries  before  terminating,  to  avoid  unwanted  effects  on  the 
behavior  of  subsequent  processes. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 
None 
Example 

.^ii^fi^i^f**********^***************************:^^****^^**********^^^*^^^; 

;  Function  44H,  Subfunction  OBH:  ; 

;  lOCTL  Change  Sharing  Retry  Count  ; 

f  r 

;  int  ioctl_set_retry (num_retries, wait-time)  ; 

;  int  num_retries;  ; 

;  int  wait-time;  ; 

f  ; 

;  Returns  0  for  success,  otherwise  returns  error  code.  ; 

r  t 

cProc  ioctl— set— retry, PUBLIC, <ds, si> 

parmW  num-retries 


parmW 

wait. 

-time 

cBegin 

mov 

dx,  num_retries 

;  Get  parameters. 

mov 

cx, wait— time 

mov 

ax, 440bh 

;  Set  function  code.  Subfunction  OBH 

int 

21h 

;  Call  MS-DOS. 

jc 

isrx 

;  Branch  on  error. 

xor 

ax,  ax 

isrx : 

cEnd 
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Interrupt  21H  (33)  3.2 

Function  44H  (68)  Subfunction  OCH 

lOCTL:  Generic  I/O  Control  for  Handles 


Function  44H  Subfunction  OCH  sets  or  gets  the  output  iteration  count  for  character- 
oriented  devices.  See  also  Appendix  A:  MS-DOS  Version  3.3. 

To  Call 

AH 
AL 
BX 
CH 

CL 

DS:DX 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  CL  was  65H  on  call: 

DS:DX  =  segment:offset  of  iteration-count  word 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

06H  invalid  handle 

Programmer’s  Notes 

•  The  iteration  count  controls  the  number  of  times  the  device  driver  tries  to  send  output 
to  the  printer  before  assuming  that  the  device  is  busy. 

•  With  MS-DOS  version  3.2,  only  category  code  05H  (printer)  is  supported  by  this 
subfunction. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

None 


=  44H 
=  0CH 
=  handle 
=  category  code: 

05H  printer 

=  function  (minor)  code: 

45H  set  iteration  count 

65H  get  iteration  count 

=  segment:offset  of  2-byte  buffer  receiving  or  containing  iteration-count  word 
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Example 


Function  44H,  Subfunction  OCH: 

Generic  lOCTL  for  Handles 

int  ioctl_char_generic (handle, category, function, pbuffer) 
int  handle; 
int  category; 
int  function; 
int  *pbuffer; 

Returns  0  for  success,  otherwise  returns  error  code. 


ioctl_char_generic, PUBLIC,  <ds> 

handle 

category 

function 

pbuffer 


cProc 

parmW 

parmB 

parmB 

parmDP 

cBegin 


mov 

bx, handle 

mov 

ch, category 

mov 

cl, function 

loadDP 

ds, dx, pbuffer 

mov 

ax, 440ch 

int 

21h 

jc 

icgx 

xor 

ax,  ax 

Get  device  handle. 

Get  category 
and  function. 

Get  pointer  to  data  buffer. 

Set  function  code.  Subfunction  OCH 
Call  MS-DOS. 

Branch  on  error. 


icgx: 

cEnd 
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Interrupt  21H  (33)  3.2 

Function  44H  (68)  Subfunction  ODH 

lOCTL:  Generic  I/O  Control  for  Block  Devices 


Function  44H  Subfunction  ODH  includes  six  input/output  tasks,  or  minor  functions,  related 
to  block-oriented  devices.  The  tasks  perform  the  following  operations:  set  or  get  device 
parameters;  write,  read,  format  and  verify,  or  verify  tracks  on  a  logical  drive. 

This  entry  covers  general  information  on  Subfunction  ODH.  Details  on  each  minor  code 
are  presented  in  subsequent  entries. 

ToCaU 

AH 
AL 
BL 
CH 

CL 


DS:DX 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  CL  was  6OH  or  6IH  on  call: 

DS:DX  =  segment:offset  of  parameter  block 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

02H  invalid  drive 

Programmer’s  Notes 

•  Set  Device  Parameters  (minor  code  40H)  must  be  used  before  an  attempt  to  write, 
read,  format,  or  verify  a  track  on  a  logical  drive.  In  general,  the  following  sequence 
applies  to  any  of  these  operations: 


=  44H 
=  0DH 

=  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 
=  category  code: 

OSH  disk  drive 

=  function  (minor)  code: 

40H  set  parameters  for  block  device 

41H  write  track  on  logical  drive 

42H  format  and  verify  track  on  logical  drive 

6OH  get  parameters  for  block  device 

6IH  read  track  on  logical  drive 

62H  verify  track  on  logical  drive 

=  segment:offset  of  parameter  block 
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1 .  Get  the  current  parameters  (minor  code  60H).  Examine  and  save  them. 

2.  Set  the  new  parameters  (minor  code  40H). 

3.  Perform  the  task. 

4.  Retrieve  the  original  parameters  and  restore  them  (minor  code  40H). 

•  With  version  3  2  of  MS-DOS,  only  category  code  OSH  is  supported  by  this  subfunction. 

•  Parameter  blocks  in  the  data  buffer  vary  with  the  task  being  performed. 

Related  Functions 
None 
Example 


Function  44H,  Subfunction  ODH: 

Generic  lOCTL  for  Block  Devices 

int  ioctl_block_generic (drv_ltr, category, func, pbuf fer) 
int  drv_ltr; 
int  category;  ’ 
int  func; 
char  *pbuffer; 

Returns  0  for  success,  otherwise  returns  error  code. 


cProc 

parmB 

parmB 

parmB 

parmDP 

cBegin 


ibg: 


ibgx : 
cEnd 


ioctl_block_generic, PUBLIC, <ds> 

drv_ltr 

category 

func 

pbuffer 


mov 

bl, drv_ltr 

;  Get  drive  letter. 

or 

bl,bl 

;  Leave  0  alone. 

jz 

ibg 

and 

bl,not  20h 

;  Convert  letter  to  uppercase. 

sub 

bl, 'A'-1 

;  Convert  to  drive  number:  'A'  =  1 
;  'B*  =2,  etc. 

;  Get  category 
;  and  function. 

;  Get  pointer  to  data  buffer. 

;  Set  function  code.  Subfunction  ODH. 
;  Call  MS-DOS. 

;  Branch  on  error. 


mov  ch, category 

mov  cl, func 

loadDP  ds, dx, pbuf fer 
mov  ax,440dh 

int  21h 

jc  ibgx 

xor  ax, ax 
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Interrupt  21H  (33) 

Function  44H  (68)  Subfunction  ODH 
Minor  Code  40H 

lOCTL:  Generic  I/O  Control  for  Block  Devices:  Set  Device  Parameters 


Function  44H  Subfunction  ODH  minor  code  40H  sets  device  parameters  in  the  parameter 
block  pointed  to  by  DS:DX. 

To  Call 

AH 
AL 
BL 
CH 

CL 

DS:DX 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

02H  invalid  drive 

Programmer's  Notes 

•  The  parameter  block  is  formatted  as  follows: 


=  44H 
=  0DH 

=  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 
=  category  code: 

OSH  disk  drive 
=  40H 

=  segment:offset  of  parameter  block 


Special-functions  field:  offset  OOH,  length  1  byte 
Bit  Value  Meaning 


0  0 
1 

1  0 
1 


Device  BIOS  parameter  block  (BPB)  field  contains  a  new 
default  BPB. 

Use  current  BPB. 

Use  all  fields  in  parameter  block. 

Use  track  layout  field  only. 


(more) 
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Special-functions  field:  offset  OOH,  length  1  byte  (continued) 

Bit  Value  Meaning 

2  0  Sectors  in  track  may  be  different  sizes.  (This  setting  should  not 

be  used.) 

1  Sectors  in  track  are  all  same  size;  sector  numbers  range  from  1 

to  the  total  number  of  sectors  in  the  track.  (This  setting 
should  always  be  used.) 

3-7  0  Reserved. 


Device  type  field:  offset  OlH,  lengthlbyte 

Value  Meaning 

OOH  320/360  KB  5.25-inch  disk 

OlH  1.2  MB  5.25-inch  disk 

02H  720  KB  3.5-inch  disk 

03H  Single-density  8-inch  disk 

04H  Double-density  8-inch  disk 

05H  Fixed  disk 

06H  Tape  drive 

07H  Other  type  of  block  device 


Device  attributes  field:  offset  02H,  length  1  word 
Bit  Value  Meaning 


0  0 

1 

1  0 

1 

2-15  0 


Removable  storage  medium 
Nonremovable  storage  medium 
Door  lock  not  supported 
Door  lock  supported 
Reserved 


Number  of  cylinders  field:  offset  04H,  length  1  word 
Meaning:  Maximum  number  of  cylinders  supported;  set  by  device  driver 


Media  type  field:  offset  06H,  lengthlbyte 

Value  Meaning 

OOH  (default)  1.2  MB  5.25-inch  disk 
OlH  320/360  KB  5.25-inch  disk 
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Device  BPB  field:  offset  07H,  length  31  bytes. 

Meaning:  See  Programmer’s  Note  below. 

If  bit  0  =  0  in  special-functions  field,  this  field  contains  the  new  default  BPB  for  the 
device. 

If  bit  0  =  1  in  special-functions  field,  BPB  in  this  field  is  returned  by  the  device  driver 
in  response  to  subsequent  Build  BPB  requests. 


Track  layout  field:  offset  26H,  variable-length  table 

Length  Meaning 

Word  Number  of  sectors  in  track 

Word  Number  of  first  sector  in  track  * 

Word  Size  of  first  sector  in  track  * 


Word  Number  of  last  sector  in  track 

Word  Size  of  last  sector  in  track 


•Sector  number  and  sector  size  fields  are  repeated  for  each  sector  on  the  track.  If  bit  2  of  the 
special-functions  field  is  set,  all  sector  sizes  in  the  track  layout  field  must  be  the  same. 

•  The  device  BPB  field  is  a  31-byte  data  structure.  Information  contained  in  the  device 
BPB  field  describes  the  current  disk  and  disk  control  areas.  The  device  BPB  field  is 
formatted  as  follows: 


Byte  Meaning 


OO-OIH 

Number  of  bytes  per  sector 

02H 

Number  of  sectors  per  allocation  unit 

03-04H 

Number  of  sectors  reserved,  beginning  at  sector  0 

05H 

Number  of  file  allocation  tables  (FATs) 

06-07H 

Maximum  number  of  root-directory  entries 

08-09H 

Total  number  of  sectors 

OAH 

Media  descriptor 

OB-OCH 

Number  of  sectors  per  FAT 

OD-OEH 

Number  of  sectors  per  track 

0F~10H 

Number  of  heads 

11-14H 

Number  of  hidden  sectors 

15-lFH 

Reserved 
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•  When  Set  Device  Parameters  (minor  code  40H)  is  used,  the  number  of  cylinders 
should  not  be  reset — some  or  all  of  the  volume  may  become  inaccessible. 

•  Subfunction  ODH  minor  code  60H  performs  the  complementary  action,  Get  Device 
Parameters. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

None 

Example 

None 
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Interrupt  21H  (33) 

Function  44H  (68)  Subfunction  ODH 
Minor  Code  60H 

lOCTL:  Generic  I/O  Control  for  Block  Devices:  Get  Device  Parameters 


Function  44H  Subfunction  ODH  minor  code  60H  gets  device  parameters  in  the  parameter 
block  pointed  to  by  DS:DX. 

ToCaU 

AH 
AL 
BL 
CH 

CL 

DS:DX 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

02H  invalid  drive 

Programmer’s  Notes 

•  The  parameter  block  is  formatted  as  follows: 


=  44H 
=  0DH 

=  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 
=  category  code: 

OSH  disk  drive 
=  60H 

=  segment:offset  of  parameter  block 


Special'functions  field:  offset  OOH,  length  1  byte 
Bit  Value  Meaning 


0 


0 

1 


1~7  0 


Returns  default  BIOS  parameter  block  (BPB)  for  the  device. 
Returns  BPB  that  the  Build  BPB  device  driver  call  would 
return. 

Reserved  (must  be  zero). 
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Device  type  field:  offset  OlH,  lengthlbyte 

Value  Meaning 

OOH  320/360  KB  5.25-inch  disk 

OlH  1.2  MB  5.25-inch  disk 

.02H  720  KB  3.5-inch  disk 

03H  Single-density  8-inch  disk 

04H  Double-density  8-inch  disk 

05H  Fixed  disk 

06H  Tape  drive 

07H  Other  type  of  block  device 


Device  attributes  field:  offset  02H,  length  1  word 


Bit  Value  Meaning 


0  0 

1 

1  0 

1 

2~15  0 


Removable  storage  medium 
Nonremovable  storage  medium 
Door  lock  not  supported 
Door  lock  supported 
Reserved 


Number  of  cylinders  field:  offset  04H,  length  1  word 
Meaning:  Maximum  number  of  cylinders  supported;  set  by  device  driver 


Media  type  field:  offset  06H,  length  1  byte 

Value  Meaning 

OOH  (default)  1,2  MB  5.25-inch  disk 
OlH  320/360  KB  5.25-inch  disk 


Device  BPB  field:  offset  07H,  length  31  bytes 
Meaning:  See  Programmer’s  Note  below. 


If  bit  0  =  0  in  special-functions  field,  this  field  contains  the  new  default  BPB  for  the 
device. 

If  bit  0  =  1  in  special-functions  field,  BPB  in  this  field  is  returned  by  the  device  driver 
in  response  to  subsequent  Build  BPB  requests. 
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Track  layout  field:  offset  26H 

Unused 


•  The  device  BPB  field  is  a  31-byte  data  structure.  Information  contained  in  the  device 
BPB  field  describes  the  current  disk  and  disk  control  areas.  The  device  BPB  field  is 
formatted  as  follows: 


Byte 

Meaning 

OO-OIH 

Number  of  bytes  per  sector 

02H 

Number  of  sectors  per  allocation  unit 

03-04H 

Number  of  sectors  reserved,  beginning  at  sector  0 

05H 

Number  of  file  allocation  tables  (FATs) 

06-07H 

Maximum  number  of  root-directory  entries 

08-09H 

Total  number  of  sectors 

OAH 

Media  descriptor 

OB-OCH 

Number  of  sectors  per  FAT 

OD-OEH 

Number  of  sectors  per  track 

OF-lOH 

Number  of  heads 

11-14H 

Number  of  hidden  sectors 

15-lFH 

Reserved 

•  Subfunction  ODH  minor  code  40H  performs  the  complementary  action,  Set  Device 
Parameters. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

None 

Example 

None 
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Interrupt  21H  (33) 

Function  44H  (68)  Subfunction  ODH 
Minor  Codes  4lH  and  6lH 

lOCTL:  Generic  I/O  Control  for  Block  Devices:  Write  Track  on  Logical  Drive; 
Read  Track  on  Logical  Drive 


Function  44H  Subfunction  ODH  minor  code  41H  writes  a  track  on  the  logical  drive  speci¬ 
fied  in  BL  and  minor  code  6lH  reads  a  track  on  the  logical  drive  specified  in  BL,  using  in¬ 
formation  in  the  parameter  block  pointed  to  by  DS:DX. 

ToCaU 

AH  =  44H 

AL  =  ODH 

BL  =  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 

CH  =  category  code: 

OSH  disk  drive 

CL  =  function  (minor)  code: 

41H  write  a  track 

6lH  read  a  track 

DS:DX  =  segment:offset  of  parameter  block 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

02H  invalid  drive 
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Programmer’s  Notes 

•  The  parameter  block  is  formatted  as  follows: 


Offset 

Size 

Meaning 

OOH 

Byte 

Special-functions  field;  must  be  0. 

OlH 

Word 

Head  field;  contains  number  of  disk  head  used  for  read/write. 

03H 

Word 

Cylinder  field;  contains  number  of  disk  cylinder  used  for  read/ 
write. 

05H 

Word 

First-sector  field;  contains  number  of  first  sector  to  read  or 
write  (first  sector  on  track  =  sector  0). 

07H 

Word 

Number-of-sectors  field;  contains  number  of  sectors  to 
transfer. 

09H 

Dword 

Transfer  address  field;  contains  address  of  buffer  to  use  for 

data  transfer. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 
None 
Example 

None 
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Interrupt  21H  (33) 

Function  44H  (68)  Subfunction  ODH 
Minor  Codes  42H  and  62H 

lOCTL:  Generic  I/O  Control  for  Block  Devices:  Format  and  Verify  Track  on 
Logical  Drive;  Verify  Track  on  Logical  Drive 


Function  44H  Subfunction  ODH  minor  code  42H  formats  and  verifies  a  track  on  the  speci¬ 
fied  logical  drive  and  minor  code  62H  verifies  a  track  on  the  specified  logical  drive,  using 
information  in  the  parameter  block  pointed  to  by  DS:DX. 

ToCaU 

AH 
AL 
BL 
CH 

CL 

DS:DX 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

02H  invalid  drive 

Programmer’s  Notes 

•  The  parameter  block  is  formatted  as  follows: 


=  44H 
=  0DH 

=  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 
=  category  code: 

OSH  disk  drive 
=  function  (minor)  code: 

42H  format  and  verify 

62H  verify 

=  segment:offset  of  parameter  block 


Offset  Size  Meaning 

OOH  Byte  Special-functions  field;  must  be  0. 

OlH  Word  Head  field;  contains  number  of  disk  head  used  for  format/ 

verify. 

03H  Word  Cylinder  field;  contains  number  of  cylinder  used  for  format/ 

verify. 
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•  This  driver  subfunction  allows  the  writing  of  generic  formatting  programs  that  are 
minimally  hardware  dependent. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

None 

Example 

None 
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Interrupt  21H  (33)  3.2 

Function  44H  (68)  Subfunctions  OEH  and  OFH 

lOCTL:  Get  Logical  Drive  Map;  Set  Logical  Drive  Map 

Function  44H  Subfunction  OEH  allows  a  process  to  determine  whether  more  than  one  logi¬ 
cal  drive  is  assigned  to  a  block  device.  Subfunction  OFH  sets  the  next  logical  drive  number 

that  will  be  used  to  reference  a  block  device. 

To  Call 

AH  =44H 

AL  =  OEH  get  logical  drive  map 

OFH  set  logical  drive  map 

BL  =  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AL  =  mapping  code: 

OOH  only  one  letter  assigned  to  the  block  device 

01  -  lAH  logical  drive  letter  (A  through  Z)  mapped  to  block  device 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

OFH  invalid  drive 

Programmer’s  Notes 

•  If  a  drive  has  not  been  assigned  a  logical  mapping  with  Function  44H  Subfunction 
OFH,  the  logical  and  physical  drive  references  are  the  same.  (The  default  is  that  logical 
drive  A  and  physical  drive  A  both  refer  to  physical  drive  A.) 

•  If  this  function  is  used  to  map  logical  drives  to  physical  drives,  the  result  is  similar  to 
MS-DOS’s  treatment  of  a  single  physical  drive  as  both  A  and  B  on  a  system  with  one 
floppy-disk  drive.  With  MS-DOS  version  3.2,  however,  the  installable  device  driver 
DRIVER.SYS  extends  this  type  of  physical/logical  referencing  to  other  drives.  There¬ 
fore,  processes  can  prompt  for  disks  themselves,  instead  of  using  the  prompt  provided 
by  MS-DOS. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 
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Related  Fimctioiis 
None 
Example 


;  Function  44H,  Subfunctions  OEH,  OFH:  ; 
;  lOCTL  Get /Set  Logical  Drive  Map  ; 

;  int  ioctl_drive_owner (setflag,  drv_ltr)  ; 
;  int  setflag;  ; 
;  int  drv_ltr;  ; 

;  Set  setflag  =  1  to  change  drive's  map,  0  to  get  ; 
;  current  map.  ; 
/  ; 
;  Returns  -1  for  all  errors,  otherwise  returns  ; 
;  the  block  device's  current  logical  drive  letter.  ; 

•************************************i¥**************nm::ti******- 


cProc  ioctl_drive_owner, PUBLIC 
parmB  setflag 


parmB 

drv_ltr 

cBegin 

mov 

al, setflag 

and 

al,  1 

add 

al, Oeh 

mov 

bl, drv_ltr 

or 

bl,bl 

jz 

ido 

and 

bl,not  20h 

sub 

bl, 'A'-1 

ido: 

mov 

bh,0 

mov 

ah,44h 

int 

21h 

mov 

ah,  0 

jnc 

idox 

mov 

ax, -1 - 'A' 

idox: 

add 

ax, 'A' 

cEnd 

Load  setflag. 

Keep  only  Isb. 

AL  =  OEH  for  get,  OFH  for  set. 
Get  drive  letter. 

Leave  0  alone. 

Convert  letter  to  uppercase. 
Convert  to  drive  number:  ’A'  =  1 
'B'  =  2,  etc. 


Set  function  code. 
Call  MS-DOS. 

Clear  high  byte. 
Branch  if  no  error. 
Return  -1  for  errors. 

Return  drive  letter. 
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Interrupt  21H  (33)  2.0  and  later 

Function  45H  (69) 

Duplicate  File  Handle 


Function  45H  obtains  an  additional  handle  for  a  currently  open  file  or  device. 

ToCaU 

AH  =  45H 

BX  =  handle  for  open  file  or  device 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX  =  new  handle  number 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

04H  too  many  open  files 

06H  invalid  handle 

Programmer’s  Notes 

•  The  file  pointer  for  the  new  handle  is  set  to  the  same  position  as  the  pointer  for  the 
original  handle.  Any  subsequent  changes  to  the  file  are  reflected  in  both  handles. 
Thus,  using  either  handle  for  a  read  or  write  operation  moves  the  file  pointer  associ¬ 
ated  with  both. 

•  Function  45H  is  often  used  to  duplicate  the  handle  assigned  to  standard  input  (0)  or 
standard  output  (1)  before  a  call  to  Function  46H  (Force  Duplicate  File  Handle).  The 
handle  forced  by  Function  46H  can  then  be  used  for  redirected  input  or  output  from 
or  to  a  file  or  device. 

•  Another  use  for  Function  45H  is  to  keep  a  file  open  while  its  directory  entry  is  being 
updated  to  reflect  a  change  in  length.  If  a  new  handle  is  obtained  with  Function  45H 
and  then  closed  with  Function  3EH  (Close  File),  the  directory  and  FAT  entries  for  the 
file  are  updated.  At  the  same  time,  because  the  original  handle  remains  open,  the  file 
need  not  be  reopened  for  additional  read  or  write  operations. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 
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Related  Function 

46H  (Force  Duplicate  File  Handle) 

Example 

;  Function  45H:  Duplicate  File  Handle 

;  int  dup_handle (handle) 

;  int  handle; 

/ 

;  Returns  -1  for  errors, 

;  otherwise  returns  new  handle. 

;*:|cHc4c*****!H*«*4!*********4c*4c*4c****4c4c«!|c««Hc*Hc***iH!f;4c**Hc*****«i|c*>K-* 


cProc 

dup_handle, PUBLIC 

parmW 

handle 

cBegin 

mov 

bx, handle 

;  Get  handle  to  copy. 

mov 

ah,45h 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  to  duplicate  handle 

jnb 

dup_ok 

;  Branch  if  copy  was  successful. 

mov 

ax,  -1 

;  Else  return  -1 . 

dup_ok : 

cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  46H  (70) 

Force  Duplicate  File  Handle 

Function  46H  forces  the  open  handle  specified  in  CX  to  track  the  same  file  or  device  speci¬ 
fied  by  the  handle  in  BX. 

ToCaU 

AH  =  46H 

BX  =  open  handle  to  be  duplicated 
CX  =  open  handle  to  be  forced 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

04H  too  many  open  files 

06H  invalid  handle 

Programmer’s  Notes 

•  The  handle  in  BX  must  refer  either  to  an  open  file  or  to  any  of  the  five  standard  han¬ 
dles  reserved  by  MS-DOS:  standard  input,  standard  output,  standard  error,  standard 
auxiliary,  or  standard  printer. 

•  If  the  handle  in  CX  refers  to  an  open  file,  the  file  is  closed. 

•  The  file  pointer  for  the  duplicate  handle  is  set  to  the  same  position  as  the  pointer  for 
the  original  handle.  Changing  the  position  of  either  file  pointer  moves  the  pointer 
associated  with  the  other  handle  as  well. 

•  When  used  with  Function  45H  (Duplicate  File  Handle),  Function  46H  can  be  used  to 
redirect  input  and  output  as  follows: 

1.  Duplicate  the  handle  from  which  input  or  output  will  be  redirected  with  Func¬ 
tion  45H  (Duplicate  File  Handle).  Save  the  duplicated  handle  for  later  reference 
(Step  3). 

2.  Call  Function  46H,  with  the  handle  to  be  redirected  from  in  the  CX  register  and 
the  handle  to  be  redirected  to  in  the  BX  register. 

3.  To  restore  I/O  redirection  to  its  original  state,  call  Function  46H  again,  with  the 
redirected  file  handle  from  Step  2  in  the  CX  register  and  the  duplicated  file  han¬ 
dle  from  Step  1  in  the  BX  register. 
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This  procedure  is  normally  used  to  redirect  a  standard  device,  but  it  can  redirect  any 
device  referenced  by  handles. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 

error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

45H  (Duplicate  File  Handle) 

Example 


Function  46H:  Force  Duplicate  File  Handle 

int  dup_handle2 (existhandle, newhandle) 
int  existhandle, newhandle; 

Returns  -1  for  errors, 

otherwise  returns  newhandle  unchanged. 


cProc  dup_handle2, PUBLIC 

parmW  existhandle 
parmW  newhandle 
cBegin 

mov  bx, existhandle  ; 

mov  cx, newhandle  ; 

mov  ah,46h  ; 

int  21 h  ; 

mov  ax, newhandle  ; 

jnb  dup2_ok  ; 

mov  ax,-1  ; 

dup2_ok : 
cEnd 


Get  handle  of  existing  file. 

Get  handle  to  copy  into. 

Close  handle  CX  and  then 
duplicate  BX's  handle  into  CX. 
Prepare  return  value. 

Branch  if  close/copy  was  successful. 
Else  return  -1 . 
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Interrupt  21H  (33)  2.0  and  later 

Function  47H  (71) 

Get  Current  Directory 


Function  47H  returns  the  path,  excluding  the  drive  and  leading  backslash,  of  the  current 

directory  for  the  specified  drive. 

ToCaU 

AH  =47H 

DL  =  drive  number  (0  =  default  drive,  1  =  drive  A,  2  =  drive  B,  and  so  on) 

DS:SI  “  segmentioffset  of  64-byte  buffer 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

Buffer  is  filled  in  with  ASCII2  pathname. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OFH  invalid  drive 

Programmer’s  Notes 

•  The  string  representing  the  pathname  is  returned  as  a  null-terminated  ASCII  string 
(ASCIIZ). 

•  This  function  does  not  return  an  error  if  the  buffer  is  too  small  or  is  incorrectly  iden¬ 
tified.  MS-DOS  pathnames  can  be  as  long  as  64  characters;  if  the  buffer  is  less  than  64 
bytes,  MS-DOS  can  overwrite  sections  of  memory  outside  the  buffer. 

•  The  path  returned  by  Function  47H  starts  at  the  root  directory  and  fully  specifies  the 
path  to  the  current  directory  but  does  not  include  a  drive  code  or  a  leading  backslash 
(\)  character. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

3BH  (Change  Current  Directory) 
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Example 


Function  47H:  Get  Current  Directory 

int  get_dir (drive_ltr,pbuf fer) 
int  drive_ltr; 
char  *pbuffer; 

Returns  -1  for  bad  drive, 
otherwise  returns  pointer  to  pbuffer. 

********^********4i************************rti***:ii**:iiitidtiiiiiti****** 


cProc 

parmB 

parmDP 

cBegin 


gdir : 


gd_ok : 
cEnd 


get_dir, PUBLIC,  <ds,  si> 

drive_ltr 

pbuffer 


loadDP 

ds, si, pbuffer 

;  Get  pointer  to  buffer. 

mov 

dl, drive_ltr 

;  Get  drive  number. 

or 

dl,dl 

;  Leave  0  alone. 

jz 

gdir 

and 

dl,not  20h 

;  Convert  letter  to  uppercase 

sub 

1 

< 

1 — 1 

;  Convert  to  drive  number:  'A' 

;  'B'  =  2,  etc. 

mov 

ah,47h 

;  Set  function  code. 

int 

21h 

;  Call  MS-DOS. 

mov 

ax,  si 

;  Return  pointer  to  buffer  .  .  . 

jnb 

gd_ok 

mov 

ax,  -1 

;  ...  unless  an  error  occurred 
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Interrupt  21H  (33)  2.0  and  later 

Function  48H(72) 

Allocate  Memory  Block 


Function  48H  allocates  a  block  of  memory,  in  paragraphs  (1  paragraph  =  l6  bytes),  to  the 

requesting  process. 

ToCaU 

AH  =  48H 

BX  =  number  of  paragraphs  to  allocate 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX  =  segment  address  of  base  of  allocated  block 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

07H  memory  control  blocks  damaged 

08H  insufficient  memory  to  allocate  as  requested 

BX  =  size  of  largest  available  block  (paragraphs) 

Programmer’s  Notes 

•  If  the  allocation  succeeds,  the  address  returned  in  AX  is  the  segment  of  the  base  of  the 
block.  This  address  would  be  copied  to  a  segment  register  (usually  DS  or  ES)  to  access 
the  memory  within  the  block. 

•  If  the  amount  of  memory  requested  is  greater  than  the  amount  in  any  available  con¬ 
tiguous  block  of  memory,  the  number  of  paragraphs  in  the  largest  available  memory 
block  is  returned  in  the  BX  register. 

•  The  default  memory-management  strategy  in  MS-DOS  is  to  choose  the  first  con¬ 
tiguous  block  of  memory  that  fits  the  request,  no  matter  how  good  the  fit.  With  MS- 
DOS  versions  3.0  and  later,  however,  the  memory-management  strategy  can  be  altered 
with  Function  58H  (Get/Set  Allocation  Strategy). 

•  If  a  process  actively  allocates  and  frees  blocks  of  memory,  the  transient  program  area 
(TPA)  can  become  fragmented — that  is,  small  blocks  of  memory  can  be  orphaned 
because  the  memory-management  strategy  seeks  contiguous  blocks  of  memory. 

•  If  a  process  writes  to  memory  outside  the  limits  of  the  allocated  block,  it  can  destroy 
control  structures  for  other  memory  blocks.  This  could  result  in  failure  of  subsequent 
memory-management  functions,  and  it  will  cause  MS-DOS  to  print  an  error  message 
and  halt  when  the  process  terminates. 
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•  Initially,  the  MS-DOS  loader  allocates  all  available  memory  to  .COM  programs.  Func¬ 
tion  4AH  (Resize  Memory  Block)  can  free  memory  for  dynamic  reallocation  by  a 
process  or  by  its  children. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

49H  (Free  Memory  Block) 

4AH  (Resize  Memory  Block) 

58H  (Get/Set  Allocation  Strategy) 

Example 

; 

;  Function  48H:  Allocate  Memory  Block  ; 

f  / 

;  int  get_block {nparas,pblocksegp,pmaxparas)  ; 

;  int  nparas, ♦pblockseg, *pmaxparas;  / 

; 

;  Returns  0  if  nparas  are  allocated  OK  and  ; 

;  pblockseg  has  segment  address  of  block,  ; 

;  otherwise  returns  error  code  with  pmaxparas  ; 

;  set  to  maximum  block  size  available.  ; 

; 


cProc 

get_block, PUBLIC, ds 

parmW 

nparas 

parmDP 

pblockseg 

parmDP 

pmaxparas 

cBegin 

mov 

bx, nparas 

r  Get  size  request. 

mov 

ah,48h 

r  Set  function  code. 

int 

21h 

r  Ask  MS-DOS  for  memory. 

mov 

cx,bx 

r  Save  BX. 

loadDP 

ds, bx, pmaxparas 

mov 

[bx] , cx 

Return  result,  assuming  failure. 

jb 

gb_err 

Exit  if  error,  leaving  error  code 
in  AX. 

loadDP 

ds,bx, pblockseg 

mov 

[bx] , ax 

r  No  error,  so  store  address  of  block 

xor 

ax,  ax 

;  Return  0 . 

gb_err : 
cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  49H  (73) 

Free  Memory  Block 


Function  49H  releases  a  block  of  memory  previously  allocated  with  Function  48H  (Allo¬ 
cate  Memory  Block). 

ToCaU 

AH  =  49H 

ES  =  segment  address  of  memory  block  to  release 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

07H  memory  control  blocks  damaged 

09H  incorrect  memory  segment  specified 

Programmer’s  Notes 

•  The  memory  segment  pointed  to  by  ES:0000H  must  have  been  allocated  by  Function 
48H  (Allocate  Memory  Block). 

•  If  a  program  has  inadvertently  damaged  any  of  the  system’s  memory  control  blocks 
by  writing  outside  an  allocated  block,  an  attempt  to  free  allocated  memory  results  in 
error  code  07H  (memory  control  blocks  damaged). 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

48H  (Allocate  Memory  Block) 

4AH  (Resize  Memory  Block) 

58H  (Get/Set  Allocation  Strategy) 
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Example 


Function  49H:  Free  Memory  Block 

int  free_block (blockseg) 
int  blockseg; 

Returns  0  if  block  freed  OK, 
otherwise  returns  error  code. 


cProc 

parmW 

cBegin 


fb_err : 
cEnd 


free_block, PUBLIC 
blockseg 


mov 

es, blockseg 

; 

mov 

ah,49h 

; 

int 

21h 

; 

jb 

fb_err 

; 

xor 

ax,  ax 

; 

Get  block  address. 

Set  function  code. 

Ask  MS-DOS  to  free  memory. 
Branch  on  error. 

Return  0  if  successful. 
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Interrupt  21H  (33)  2.0  and  later 

Function  4AH  (74) 

Resize  Memory  Block 


Function  4AH  adjusts  the  size  of  a  previously  allocated  block  of  memory. 

ToCaU 

AH  =4AH 

BX  =  new  size  of  memory  block,  in  paragraphs 

ES  =  segment  address  of  previously  allocated  memory  block 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

07H  memory  control  blocks  damaged 

OSH  insufficient  memory  to  allocate  as  requested 

09H  incorrect  memory  segment  specified 

BX  =  maximum  number  of  paragraphs  available  (if  an  increase  was  requested) 

Programmer’s  Notes 

•  Function  4AH  can  be  used  to  change  the  size  of  a  memory  block  previously  allocated 
with  Function  48H  (Allocate  Memory  Block)  or  to  modify  the  amount  of  memory 
originally  allocated  to  a  process  by  MS-DOS. 

•  If  a  process  is  denied  an  increase  in  the  amount  of  memory  it  has  been  allocated,  MS- 
DOS  places  the  size  of  the  largest  contiguous  block  available  in  the  BX  register.  The 
process  can  then  notify  the  user  of  the  problem  and  exit,  or  it  can  continue  to  operate 
in  a  reduced  memory  environment. 

•  Because  the  MS-DOS  loader  allocates  all  available  memory  to  .COM  programs,  such  a 
program  should  use  Function  4AH  immediately  (with  the  segment  address  of  its  pro¬ 
gram  segment  prefix,  or  PSP)  to  release  any  memory  that  is  not  needed.  This  is  man¬ 
datory  if  the  .COM  program  will  either  allocate  memory  dynamically  or  use  Function 
4BH  (Load  and  Execute  Program)  to  load  a  child  process  or  overlay. 

In  addition,  if  Function  4AH  is  used  to  adjust  the  amount  of  memory  allocated  to  a 
.COM  program,  the  stack  pointer  must  be  adjusted  so  that  it  is  within  the  limits  of  the 
program’s  revised  memory  allocation. 
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•  If  this  function  is  used  to  shrink  an  allocated  block,  any  memory  above  the  new  limit 
is  not  owned  by  the  process  and  should  never  be  used.  If  this  function  is  used  to  ex¬ 
pand  an  allocated  block,  the  contents  of  memory  above  the  old  boundary  are  unpre¬ 
dictable  and  the  memory  should  be  initialized  before  use. 

•  Although  it  is  not  possible  to  predict  how  much  memory-resident  software  and  how 
many  installable  device  drivers  will  be  used  on  a  computer  system.  Function  4AH  can 
reliably  determine  the  amount  of  memory  available  to  an  application. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

48H  (Allocate  Memory  Block) 

49H  (Free  Memory  Block) 

58H  (Get/Set  Allocation  Strategy) 

Example 


Function  4AH:  Resize  Memory  Block 

int  modify_block (nparas,blockseg,pmaxparas) 
int  nparas,blockseg, *pmaxparas; 


Returns  0  if  modification  was  a  success, 
otherwise  returns  error  code  with  pmaxparas 
set  to  max  number  of  paragraphs  available. 


**illi*Hsilliiltiif^liilli*;lltiitP***********************^*********************** 


modify_block, PUBLIC, ds 

nparas 

blockseg 

pmaxparas 


cProc 
parmW 
parmW 
parmDP 
cBegin 

mov 

mov 

mov 

int 

mov 

loadDP 

mov 

jb 

xor 

mb_exit : 
cEnd 


es, blockseg 
bx, nparas 
ah, 4ah 
21h 
cx,bx 

ds,bx, pmaxparas 
[bx] , cx 
mb_exit 
ax,  ax 


Get  block  address. 

Get  nparas. 

Set  function  code. 

Ask  MS-DOS  to  change  block  size. 
Save  BX. 

Set  pmaxparas,  assuming  failure. 
Branch  if  size  change  error. 
Return  0  if  successful. 
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Interrupt  21H  (33)  2.0  and  later 

Function  4BH  (75) 

Load  and  Execute  Program  (EXEC) 

Function  4BH,  often  called  EXEC,  loads  a  program  file  into  memory  and,  optionally,  ex¬ 
ecutes  the  program.  This  function  can  also  be  used  to  load  a  program  overlay. 

ToCaU 

AH  =  4BH 

AL  =  OOH  load  and  execute  program 

03H  load  overlay 

DS:DX  =  segment:offset  of  ASCIIZ  pathname  for  an  executable  program  file 

ES:BX  =  segment:offset  of  parameter  block 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

With  MS-DOS  versions  2.x,  all  registers  except  CS  and  IP  can  be  destroyed;  with  MS-DOS 
versions  3.x,  registers  are  preserved. 

If  function  is  not  successful: 

Carry  flag  is  set. 


AX  =  error  code: 


OlH 

invalid  function  (AL  did  not  contain  OOH  or  03H) 

02H 

file  not  found 

03H 

path  not  found 

05H 

access  denied 

OSH 

insufficient  memory 

OAH 

bad  environment 

OBH 

bad  format  (AL  =  OOH  only) 

Programmer’s  Notes 

•  The  pathname  must  be  a  null-terminated  ASCII  string  (ASCIIZ). 

•  The  handles  for  any  files  opened  by  the  parent  process  before  the  call  to  Function 

4BH  are  inherited  by  the  child  process,  unless  the  parent  specified  otherwise  in  call¬ 
ing  Function  3DH  (Open  File  with  Handle). 

All  standard  devices  also  remain  open  and  available  to  the  child  process.  Thus,  the 
parent  process  can  control  the  files  used  by  the  child  process  and  control  redirection 
for  the  child  process. 
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•  If  AL  =  OOH,  the  parameter  block  is  14  bytes  long  and  formatted  in  four  parts,  as 

follows: 


Offset 

Length 

Meaning 

OOH 

Word 

Segment  address  of  environment  to  be  passed;  OOH  indi¬ 
cates  child  program  inherits  environment  of  the  current 
process. 

02H 

Dword 

Segment:offset  address  of  command  tail  for  the  new  pro¬ 
gram  segment  prefix  (PSP).  Command  tail  must  be  128 
bytes  or  fewer  and  formatted  as  a  count  byte  followed  by 
an  ASCII  string  and  terminated  by  a  carriage  return,  as 
follows: 

db  7 , ' a : mydoc ' , ODh 

The  carriage  return  is  not  included  in  the  count;  the 
command  tail  is  placed  at  offset  80H  in  the  new 
process’s  PSP. 

06H 

Dword 

Segment:offset  address  of  an  FCB  to  be  copied  to  the 
default  FCB  position  at  offset  5CH  in  the  new  process’s 
PSP. 

OAH 

Dword 

Segment:offset  address  of  an  FCB  to  be  copied  to  the 
default  FCB  position  at  offset  6CH  in  the  new  process’s 
PSP. 

If  AL  =  03H,  the  parameter  block  is  4  bytes  long  and  formatted  in  two  parts,  as 
follows: 

Offset 

Length 

Meaning 

OOH 

Word 

Segment  address  where  the  overlay  is  to  be  loaded. 

02H 

Word 

Relocation  factor  to  be  applied  to  the  code  image  (.EXE 

files  only);  not  needed  if  the  file  is  a  .COM  program  or  is 
data. 


•  The  first  2  bytes  of  the  parameter  block  for  Function  4BH  Subfunction  OOH  contain 
either  the  segment  address  for  an  environment  block  to  be  passed  to  the  new  process 
or  zero.  If  the  value  is  zero,  the  child  process  inherits  an  exact  copy  of  the  parent 
process’s  environment. 

The  environment  block  must  be  aligned  on  a  paragraph  boundary  (a  multiple  of  16 
bytes).  It  can  be  as  large  as  32  KB,  and  it  consists  of  a  block  of  ASCIIZ  strings,  each  in 
the  following  form: 
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parameter=value 
For  example: 

db  'VERIFY=ON* , 0 

The  final  string  in  the  environment  block  is  followed  by  a  second  zero  byte.  With 
MS-DOS  versions  3.0  and  later,  the  second  zero  is  followed  by  a  word  containing  a 
count  and  an  ASCIIZ  string  containing  the  drive  and  pathname  of  the  program  file. 

The  environment  passed  to  the  child  process  allows  the  parent  process  to  send  it  mes¬ 
sages  regarding  the  system  state  or  control  parameters.  The  pathname  included  with 
MS-DOS  versions  3  0  and  later  enables  the  child  process  to  determine  where  it  was 
loaded  from. 

•  If  AL  =  OOH,  MS-DOS  creates  a  PSP  for  the  new  process  and  sets  the  terminate  and 
Control-C  addresses  to  the  instruction  in  the  parent  process  that  follows  the  call  to 
Function  4BH.  If  AL  =  03H,  no  PSP  is  created. 

•  Before  AL  =  OOH  is  used  to  load  and  execute  a  process,  the  system  must  contain 
enough  free  memory  to  accommodate  the  new  process.  Function  4AH  (Resize  Mem¬ 
ory  Block)  should  be  used,  if  necessary,  to  reduce  the  amount  of  memory  allocated  to 
the  parent  process.  If  the  parent  is  a  .COM  program,  allocated  memory  must  be 
reduced,  because  a  .COM  program  is  given  ownership  of  all  available  memory  when 
it  is  executed. 

If  Function  4BH  is  called  with  AL  =  03H,  free  memory  is  not  a  factor,  because  MS-DOS 
assumes  the  new  process  is  being  loaded  into  the  calling  process’s  own  address  space. 

•  If  Function  4BH  is  called  with  AL  =  OOH,  the  child  process  remains  in  control  until  it 
executes  an  exit  request,  such  as  Function  4CH  (Terminate  Process  with  Return 
Code),  or  until  Control-C  or  Control-Break  is  received  or  a  critical  error  occurs  and  the 
user  responds  Abort  to  the  Abort,  Retry,  Ignore?  message. 

•  With  MS-DOS  versions  2.x,  SS  and  SP  must  be  saved  in  the  current  code  segment 
before  Function  4BH  is  invoked  with  AL  =  OOH.  When  the  parent  process  regains  con¬ 
trol,  all  registers  other  than  CS:IP  and  the  stack  will  most  likely  have  been  changed  by 
loading  and  executing  the  child  process. 

•  Function  4BH  with  AL  =  03H  is  useful  for  loading  program  overlays  or  for  loading  data 
to  be  used  by  the  parent  process  (if  that  data  requires  relocation). 

•  If  the  child  process  that  is  executed  attempts  to  remain  resident  through  either  Inter¬ 
rupt  27H  or  Interrupt  21H  Function  31H  (Terminate  and  Stay  Resident),  system  mem¬ 
ory  becomes  permanently  fragmented  and  subsequent  processes  can  fail  because  of 
lack  of  memory. 

•  The  EXEC  function  (with  AL  =  OOH)  is  commonly  used  to  load  a  new  copy  of 
COMMAND.COM  and  then  execute  an  MS-DOS  command  from  within  another 
program. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 
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Related  Functions 

31H  (Terminate  and  Stay  Resident) 

4CH  (Terminate  Process  with  Return  Code) 

4DH  (Get  Return  Code  of  Child  Process) 

Examples 

.HcH:H:********4c*4(4:******4c*****4‘iic*H(**!ltiie4c4c********«9|e*9K9HHc*He*4:4:4c*** 

;  Function  4BH:  Load  and  Execute  Program 

;  int  execute (pprogname,pcmdtail) 

;  char  *pprogname, *pcmdtail; 

i 

;  Returns  0  if  program  loaded,  ran,  and 

;  terminated  successfully,  otherwise  returns 

;  error  code. 

f 

•  :|e:ie:|e:)e:|c:9c:ie^%:|e4c:|e)|e4:4e:|e4i4e4i4e4e4c:ic:ie:fe:fc:|e4e:ic4E3ie:ie:tc4c4c:|c:|e:ie:ie:|c4e:|e:|e9)e9ie3ie9(e4e9|e9|e9|e3te:|e:|c%:|ca|c4e^4c 

sBegin  data 
$cmdlen  =  126 

$cmd  db  $cmdlen+2  dup  (?)  ;  Make  space  for  command  line,  plus 

;  2  extra  bytes  for  length  and 
;  carriage  return. 


$fcb 

db 

0 

;  Make  dummy  FCB. 

db 

'dummy  fcb' 

db 

o 

o 

o 

o 

;  Here's  the  EXEC  parameter  block 

$epb 

dw 

0 

;  0  means 

inherit  environment . 

dw 

dataOFFSET 

$cmd  ;  Pointer 

to  cmd  line. 

dw 

seg  dgroup 

dw 

dataOFFSET 

$fcb  ;  Pointer 

to  FCB  #1 . 

dw 

seg  dgroup 

dw 

dataOFFSET 

$fcb  ;  Pointer 

to  FCB  #2. 

dw 

seg  dgroup 

sEnd 

data 

sBegin 

code 

$sp 

dw 

0 

;  Allocate  space  in  code  seg 

$ss 

dw 

7 

;  for  saving  SS  and  SP. 

Assumes  ES,dgroup 

cProc  execute, PUBLIC, <ds, si, di> 
parmDP  pprogname 
parmDP  pcmdtail 
cBegin 

mov  cx,$cmdlen  ;  Allow  command  line  this  long. 

loadDP  ds, si, pcmdtail  ;  DS:SI  =  pointer  to  cmdtail  string. 


(more) 
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mov 

ax,seg  dgroup: 

:  $cmd  ;  Set  ES  =  data  segment . 

mov 

es,  ax 

mov 

di, dataOFFSET 

$cmd+l  ;  ES:DI  =  pointer  to  2nd  byte  0: 

;  our  command-line  buffer. 

copycmd : 

lodsb 

;  Get  next  character. 

or 

al,  al 

;  Found  end  of  command  tail? 

jz 

endcopy 

;  Exit  loop  if  so. 

stosb 

;  Copy  to  command  buffer. 

loop 

copycmd 

endcopy : 

mov 

al,  13 

stosb 

;  Store  carriage  return  at 

;  end  of  command. 

neg 

cl 

add 

cl, $cmdlen 

;  CL  =  length  of  command  tail. 

mov 

es : $cmd, cl 

;  Store  length  in  command-tail  buffer 

loadDP 

ds, dx, pprogname  ;  DS:DX  =  pointer  to  program  name. 

mov 

bx, dataOFFSET 

$epb  ;  ES:BX  =  pointer  to  parameter 

;  block. 

mov 

cs : $ss, ss 

;  Save  current  stack  SS:SP  (because 

mov 

cs : $sp, sp 

;  EXEC  function  destroys  stack) . 

mov 

ax, 4b00h 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  to  load  and  execute 

;  program. 

cli 

;  Disable  interrupts. 

mov 

ss, cs : $ss 

;  Restore  stack. 

mov 

sp, cs : $sp 

sti 

;  Enable  interrupts. 

jb 

ex_err 

;  Branch  on  error. 

xor 

ax,  ax 

;  Return  0  if  no  error. 

ex_err : 

cEnd 

sEnd  code 

Function  4BH:  Load  an  Overlay  Program 

int  load—overlay (pfilename, loadseg) 
char  *pfilename; 
int  loadseg; 

Returns  0  if  program  has  been  loaded  OK, 
otherwise  returns  error  code. 

To  call  an  overlay  function  after  it  has  been 
loaded  by  load_overlay () ,  you  can  use 
a  far  indirect  call: 


(more) 
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sBegin 

$lob 

sEnd 

sBegin 

cProc 

parmDP 

parmW 

cBegin 


;  1.  FTYPE  (far  *ovlptr)(); 

;  2.  *( (unsigned  *)&ovlptr  +  1)  =  loadseg; 

;  3.  *( (unsigned  *)&ovlptr)  =  offset; 

;  4.  (*ovlptr) (argi , arg2, arg3, . . . ) ; 

;  Line  1  declares  a  far  pointer  to  a 
;  function  with  return  type  FTYPE. 

;  Line  2  stores  loadseg  into  the  segment 
;  portion  (high  word)  of  the  far  pointer. 

;  Line  3  stores  offset  into  the  offset 
;  portion  (low  word)  of  the  far  pointer. 

;  Line  4  does  a  far  call  to  offset 
;  bytes  into  the  segment  loadseg 
;  passing  the  arguments  listed. 

;  To  return  correctly,  the  overlay  must  end  with  a  far 
;  return  instruction.  If  the  overlay  is 

;  written  in  Microsoft  C,  this  can  be  done  by 

;  declaring  the  overlay  function  with  the 
;  keyword  "far". 

data 

dw 
dw 

data 
code 

load—overlay, PUBLIC, <ds, si, di> 
pf ilename 
loadseg 


loadDP 

ds, dx,pf ilename  ;  DS:DX  =  pointer  to  program  name. 

mov 

ax,seg  dgroup: 

:$lob  ;  Set  ES  =  data  segment. 

mov 

es,  ax 

mov 

bx,dataOFFSET 

$lob  ;  ES:BX  =  pointer  to  parameter 

;  block. 

mov 

ax, loadseg 

;  Get  load  segment  parameter. 

mov 

es : [bx] , ax 

;  Set  both  the  load  and  fixup 

mov 

es : [bx+2] , ax 

;  segments  to  that  segment. 

mov 

cs :  $ss, ss 

;  Save  current  stack  SS:SP  (because 

mov 

cs : $sp, sp 

;  EXEC  function  destroys  stack) . 

mov 

ax, 4b03h 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  to  load  the  overlay. 

cli 

;  Disable  interrupts. 

;  The  overlay  parameter  block: 
;  space  for  load  segment; 

;  space  for  fixup  segment. 


(more) 
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mov 

ss,cs:$ss 

mov 

sti 

sp, cs : $sp 

jb 

lo_err 

lo_err : 

cEnd 

xor 

ax,  ax 

sEnd 

code 

;  Restore  stack. 

;  Enable  interrupts . 

;  Branch  on  error. 

;  Return  0  if  no  error 
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Interrupt  21H  (33)  2.0  and  later 

Function  4CH  (76) 

Terminate  Process  with  Return  Code 


Function  4CH  terminates  the  current  process  with  a  return  code  and  returns  control  to  the 

calling  (parent)  process. 

ToCaU 

AH  =  4CH 

AL  =  return  code 

Returns 

Nothing 

Programmer’s  Notes 

•  When  a  process  is  terminated  with  Function  4CH,  MS-DOS  restores  the  termination- 
handler  (Interrupt  22H),  Control-C  handler  (Interrupt  23H),  and  critical  error  handler 
(Interrupt  24H)  addresses  from  the  program  segment  prefix,  or  PSP  (offsets  OAH, 

OEH,  and  12H).  MS-DOS  also  flushes  the  file  buffers  to  disk,  updates  the  disk  direc¬ 
tory,  closes  all  files  with  open  handles  belonging  to  the  terminated  process,  and  then 
transfers  control  to  the  termination-handler  address. 

•  On  termination  with  Function  4CH,  all  memory  owned  by  the  process  is  freed. 

•  Function  4CH  is  the  recommended  method  for  terminating  all  processes — par¬ 
ticularly  sizable  .EXE  files — that  do  not  stay  resident.  This  function  should  be  used  in 
preference  to  the  other  termination  methods  (Interrupt  20H,  Interrupt  21H  Function 
OOH,  near  RET  for  .COM  files,  or  a  jump  to  PSPiOOOOH).  Memory-resident  programs 
should  be  terminated  with  Function  31H  (Terminate  and  Stay  Resident). 

•  A  return  code  of  OOH  is  customarily  used  to  indicate  that  the  process  executed  suc¬ 
cessfully;  a  nonzero  return  code  is  used  to  indicate  that  the  process  terminated 
because  of  an  error  or  lack  of  resources — for  example,  the  file  could  not  be  opened, 
the  process  could  not  be  allocated  sufficient  memory,  and  so  on. 

•  If  the  terminated  process  was  invoked  by  a  command  line  or  batch  file,  control 
returns  to  COMMAND.COM  and  the  transient  portion  of  the  command  interpreter  is 
reloaded,  if  necessary.  If  a  batch  file  was  in  progress,  execution  continues  with  the 
next  line  of  the  file  and  the  return  code  can  be  tested  with  an  IF  ERRORLEVEL  state¬ 
ment.  Otherwise,  the  command  prompt  is  issued. 

If  the  terminated  process  was  loaded  by  a  process  other  than  COMMAND.COM,  the 
parent  process  can  retrieve  the  child’s  return  code  with  Function  4DH  (Get  Return 
Code  of  Child  Process). 

•  In  a  networking  environment  running  under  MS-DOS  version  3.1  or  later,  all  file  locks 
should  be  removed  by  the  process  before  it  calls  Function  4CH  to  terminate. 
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Related  Functions 

OOH  (Terminate  Process) 

31H  (Terminate  and  Stay  Resident) 

4DH  (Get  Return  Code  of  Child  Process) 

Example 


;:ic«*«!|c«****4cHc**4!’lc*****««***4c****«»c*****4c**3|c*i|c«**«*««4‘**«***** 

t 

;  Function  4CH:  Terminate  Process  with  Return  Code 

;  int  terminate (returncode) 

;  int  returncode; 

;  Does  NOT  return  at  all! 

/ 

;*:ic:)e*4e**********«**«**«***4(**3ie*****«4:****iic****!ic*******3|ciie3|e**** 

cProc  terminate, PUBLIC 
parmB  returncode 
cBegin 

mov  al, returncode  ;  Set  return  code. 

mov  ah,4ch  ;  Set  function  code. 

int  21 h  ;  Call  MS-DOS  to  terminate  process. 

cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  4DH  (77) 

Get  Return  Code  of  Child  Process 


Function  4DH  retrieves  the  return  code  of  a  child  process  that  was  invoked  with  Function 
4BH  (Load  and  Execute  Program)  and  terminated  with  either  Function  31H  (Terminate 
and  Stay  Resident)  or  Function  4CH  (Terminate  Process  with  Return  Code). 

ToCaU 

AH  =  4DH 

Returns 

AH  =  termination  method: 

OOH  normal  termination  (Interrupt  20H,  or  Interrupt  21H  Function  OOH  or 
Function  4CH) 

OlH  terminated  by  entry  of  Control-C 

02H  terminated  by  critical  error  handler  (for  example,  user  responded  Abort  to 

Abort,  Retry,  Ignore?  prompt) 

03H  terminated  and  stayed  resident  (Interrupt  27H  or  Interrupt  21H  Function 

31H) 

AL  =  return  code  passed  by  child  process 

If  terminated  with  Interrupt  20H,  Interrupt  21H  Function  OOH,  or  Interrupt  27H: 

AL  =00H 

Programmer’s  Notes 

•  Function  4DH  can  be  used  only  once  to  retrieve  the  return  code  of  a  terminated 
process.  Subsequent  calls  do  not  yield  meaningful  results. 

•  Function  4DH  does  not  set  the  carry  flag  to  indicate  an  error.  If  no  previous  child 
process  exists,  the  information  returned  in  AH  and  AL  is  undefined. 

Related  Functions 

31H  (Terminate  and  Stay  Resident) 

4CH  (Terminate  Process  with  Return  Code) 
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Example 

.^Hiitiiti4titi*it:iti*iti***7ti**t/tt4^**************tti*********  ***************** 

;  Function  4DH:  Get  Return  Code  of  Child  Process 

;  int  child_ret_code 0 

;  Returns  the  return  code  of  the  last 

;  child  process. 

.iti:tiiti:ii*^itiitiiti^itiitiitiiti********************************************** 

cProc  chi ld_ret_code, PUBLIC 
cBegin 

mov  ah,4dh  ;  Set  function  code. 

int  21 h  ;  Ask  MS-DOS  to  return  code. 

cbw  ;  Convert  AL  to  a  word. 

cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  4EH  (78) 

Find  First  File 


Function  4EH  searches  the  specified  directory  for  the  first  matching  entry. 

ToCaU 

AH  =  4EH 

CX  =  attribute  word 

DS:DX  =  segmentioffset  of  ASCIIZ  pathname 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

Current  disk  transfer  area  (DTA)  contains  the  following  information  about  the  file: 


Offset  Length  (bytes)  Value 


OOH  21 

15H  1 

16H  2 

18H  2 

lAH  2 

ICH  2 

lEH  13 


Reserved  for  use  by  MS-DOS  in  subsequent  call  to 
Function  4FH  (Find  Next  File) 

File  attribute 
Time  of  last  write 
Dateof  last  write 
Low  word  of  file  size 
High  word  of  file  size 

Filename  and  extension  in  ASCIIZ  form  with  blanks 
removed  and  period  inserted  between  filename  and 
extension 


If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

02H  file  not  found 

03H  path  not  found 

12H  no  more  files;  no  match  found 

Programmer’s  Notes 

•  The  pathname  must  be  a  null-terminated  ASCII  string  (ASCIIZ). 
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•  The  filename  and  extension  portions  of  the  pathname  can  contain  the  MS-DOS  wild¬ 
cards  ?  (match  any  character)  and  ♦  (match  all  remaining  characters). 

•  The  DTA  should  be  set  with  Function  lAH  (Set  DTA  Address)  before  Function  4EH  is 
called.  If  no  DTA  address  is  set,  MS-DOS  uses  a  default  128-byte  buffer  at  offset  80H  in 
the  program  segment  prefix  (PSP). 

•  The  attribute  word  in  CX  controls  the  search  as  follows: 

-  If  the  attribute  word  is  OOH,  only  normal  files  are  included  in  the  search. 

-  If  the  attribute  word  has  any  combination  of  bits  1,  2,  and  4  (hidden,  system,  and 
subdirectory  bits)  set,  the  search  includes  normal  files  as  well  as  files  with  any  of 
the  attributes  specified. 

-  If  the  attribute  word  has  bit  3  set  (volume-label  bit),  only  a  matching  volume  label 
is  returned. 

-  Bits  0  and  5  (read-only  and  archive  bits)  are  ignored  by  Function  4EH. 

•  If  Function  4FH  (Find  Next  File)  is  used  in  conjunction  with  Function  4EH,  the  DTA 
must  be  preserved,  because  the  first  21  bytes  contain  information  needed  by  Function 
4FH. 

•  The  time  at  which  the  file  was  last  written  is  returned  as  a  binary  value  in  a  word  for¬ 
matted  as  follows: 


Bits 

Meaning 

0-4 

5-10 

11-15 

Number  of  seconds  divided  by  2 

Minutes  (0  through  59) 

Hours,  based  on  a  24-hour  clock  (0  through  23). 

The  date  on  which  the  file  was  last  written  is  returned  as  a  binary  value  in  a  word  for¬ 
matted  as  follows: 

Bits 

Meaning 

0-4 

5-8 

9-15 

Day  of  the  month 

Month  (1  =  January,  2  =  February,  3  =  March,  and  so  on) 

Number  of  the  year  minus  1980 

•  Function  4EH  is  preferred  to  Function  IIH  (Find  First  File)  because  it  fully  supports 
pathnames. 

•  Function  59H  (Get  Extended  Error  Information  )  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

IIH  (Find  First  File) 

12H  (Find  Next  File) 
lAH  (Set  DTA  Address) 

4FH  (Find  Next  File) 
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Example 


Function  4EH:  Find  First  File 

int  find-first (ppathname, attr) 
char  *ppathname; 
int  attr; 

Returns  0  if  a  match  was  found, 
otherwise  returns  error  code. 


cProc  find-first, PUBLIC, ds 
parmDP  ppathname 
parmW  attr 
cBegin 


loadDP 

ds, dx, ppathname  ; 

Get  pointer  to  pathname. 

mov 

cx,attr  ; 

Get  search  attributes. 

mov 

ah,4eh  ; 

Set  function  code. 

int 

21h 

Ask  MS-DOS  to  look  for  a  match 

jb 

ff_err  ; 

Branch  on  error. 

xor 

ax , ax  ; 

Return  0  if  no  error. 

f f_err : 
cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  4FH  (79) 

Find  Next  File 


Function  4FH  continues  a  search  initiated  by  a  previously  successful  call  to  Function  4EH 
(Find  First  File).  The  search  is  based  on  the  pathname  and  attributes  specified  in  the  call  to 
Function  4EH  and  uses  information  left  in  the  current  disk  transfer  area  (DTA)  by  the  call 
to  Function  4EH  or  by  a  preceding  call  to  Function  4FH. 

ToCaU 

AH  =  4FH 

DTA  contains  information  from  prior  search  with  Function  4EH  or  Function  4FH. 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

DTA  is  filled  in  as  for  a  call  to  Function  4EH: 


Offset 

Length  (bytes) 

Value 

OOH 

21 

Reserved  for  use  by  MS-DOS  in  subsequent  call  to 
Function  4FH 

15H 

1 

File  attribute 

16H 

2 

Time  of  last  write 

18H 

2 

Dateof  last  write 

lAH 

2 

Low  word  of  file  size 

ICH 

2 

High  word  of  file  size 

lEH 

13 

Filename  and  extension  in  ASCIIZ  form  with  blanks 
removed  and  period  inserted  between  filename  an 
extension 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

12H  no  more  files,  no  match  found,  or  no  previous  call  to  Function  4EH 
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Programmer’s  Notes 

•  If  multiple  calls  to  Function  4FH  are  used  to  find  more  than  one  matching  file,  the 
DTA  setting  (Function  lAH)  and  contents  must  be  preserved  because  they  provide  in¬ 
formation  needed  for  continuing  the  search. 

•  The  time  at  which  the  file  was  last  written  is  returned  as  a  binary  value  in  a  word  for¬ 
matted  as  follows: 


Bits 

Meaning 

0-4 

5-10 

11-15 

Number  of  seconds  divided  by  2 

Minutes  (0  through  59) 

Hours,  based  on  a  24-hour  clock  (0  through  23). 

The  date  on  which  the  file  was  last  written  is  returned  as  a  binary  value  in  a  word  for¬ 
matted  as  follows: 

Bits 

Meaning 

0-4 

5-8 

9-15 

Day  of  the  month 

Month  (1  =  January,  2  =  February,  3  =  March,  and  so  on) 

Number  of  the  year  minus  1980 

•  Function  4FH  is  preferred  to  Function  12H  (Find  Next  File)  because  it  fully  supports 
pathnames, 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

IIH  (Find  First  File) 

12H  (Find  Next  File) 
lAH  (Set  DTA  Address) 

4EH  (Find  First  File) 

Example 


Function  4FH:  Find  Next  File 
int  find-next  0 

Returns  0  if  a  match  was  found, 
otherwise  returns  error  code. 


(more) 
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cProc  find_next, PUBLIC 
cBegin 


mov 

ah,4fh 

int 

21h 

jb 

fn_err 

xor 

ax,  ax 

f  n_err ; 
cEnd 


;  Set  function  code. 

;  Ask  MS-DOS  to  look  for  the  next 
;  matching  file. 

;  Branch  on  error. 

;  Return  0  if  no  error. 
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Interrupt  21H  (33)  2  0  and  later 

Function  54H  (84) 

Get  Verify  Flag 


Function  54H  returns  the  current  value  of  the  MS-DOS  verify  flag. 

ToCaU 

AH  =  54H 

Returns 

AL  “verify flag: 

OOH  verify  off;  no  read  after  write  operation 

OlH  verify  on;  read  after  write  operation 

Programmer’s  Notes 

•  The  default  state  of  the  verify  flag  is  OOH  (off). 

•  The  state  of  the  verify  flag  can  be  changed  either  through  a  call  to  Function  2EH 
(Set/Reset  Verify  Fla^  or  by  the  user  with  the  VERIFY  ON  and  VERIFY  OFF 
commands. 

Related  Function 

Function  2EH  (Set/Reset  Verify  Flag) 

Example 


;  Function  54H:  Get  Verify  Flag 

;  int  get_verify() 

;  Returns  current  value  of  verify  flag. 


cProc  get_verify, PUBLIC 
cBegin 

mov  ah,54h 

int  21h 

cbw 


cEnd 


;  Set  function  code. 

;  Read  flag  from  MS-DOS. 

;  Clear  high  byte  of  return  value. 
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Interrupt  21H  (33)  2.0  and  later 

Function  56H  (86) 

Rename  File 


Function  56H  renames  a  file  and/or  moves  it  to  a  new  location  in  the  hierarchical  directory 
structure. 

ToCaU 

AH  =  56H 

DS:DX  =  segment:offset  of  existing  ASCIIZ  pathname  for  file 

ES:DI  =  segment:offset  of  new  ASCIIZ  pathname  for  file 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

02H  file  not  found 

03H  path  not  found 

05H  access  denied 

1 IH  not  the  same  device 

Programmer’s  Notes 

•  The  pathnames  must  be  null-terminated  ASCII  strings  (ASCIIZ). 

•  The  directory  paths  specified  in  DS:DX  and  ES:DI  need  not  be  identical.  Thus,  speci¬ 
fying  different  directory  paths  effectively  moves  a  file  from  one  directory  to  another. 

•  Function  56H  cannot  be  used  to  move  a  file  to  a  different  drive.  Both  the  existing 
pathname  and  the  new  one  must  either  contain  the  same  drive  identifier  or  default  to 
the  same  drive. 

•  If  Function  56H  returns  error  code  05H,  the  cause  can  be  any  of  the  following: 

-  The  new  pathname  would  move  the  file  to  the  root  directory,  but  the  root  directory 
is  full. 

-  A  file  with  the  new  pathname  already  exists. 

-  The  user  is  on  a  network  and  has  insufficient  access  to  either  the  existing  file  or  the 
new  subdirectory. 

•  Unlike  Function  17H  (Rename  File),  Function  56H  does  not  support  the  use  of  MS- 
DOS  wildcard  characters  (?  and  *). 
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•  Function  56H  should  not  be  used  to  rename  open  files.  An  open  file  should  be  closed 
with  Function  lOH  (Close  File  with  FCB)  or  3EH  (Close  File)  before  Function  56H  is 
called  to  rename  it. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

17H  (Rename  File) 

Example 

f*********;i^*********4f*****4fi*********************:¥************j 

;  Function  56H:  Rename  File  ; 

;  int  rename (poldpath, pnewpath)  ; 

;  char  *poldpath, *pnewpath;  ; 

/  f 

;  Returns  0  if  file  moved  OK,  ; 

;  otherwise  returns  error  code.  ; 

.4!«]t:*«**4«!t:**4(4(*******H!9t!*9|(4c*9ic4:****4:**i)‘**3ic!ie***9|c***iN*****9ic3|eiic4cii:**; 

cProc  rename, PUBLIC, <ds, di> 
parmDP  poldpath 
parmDP  pnewpath 
cBegin 


loadDP 

es, di, pnewpath 

;  ES:DI  =  pointer  to  newpath 

loadDP 

ds,dx, poldpath 

;  DS:DX  =  pointer  to  oldpath 

mov 

ah,56h 

;  Set  function  code. 

int 

21h 

;  Ask  MS-DOS  to  rename  file. 

jb 

rn_err 

;  Branch  on  error. 

xor 

ax,  ax 

;  Return  0  if  no  error. 

rn_err : 

cEnd 
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Interrupt  21H  (33)  2.0  and  later 

Function  57H  (87) 

Get/Set  Date/Time  of  File 


Function  57H  retrieves  or  sets  the  date  and  time  of  a  file’s  directory  entry. 

ToCaU 

AH  =  57H 

AL  =00H  get  date  and  time 

OlH  set  date  and  time 

BX  =  handle  number 

If  AL  =  OlH: 

CK  =  time;  binary  value  formatted  as  follows: 


Bits 

Meaning 

0-4 

5-10 

11-15 

Number  of  seconds  divided  by  2 

Minutes  (0  through  59) 

Hours,  based  on  a  24-hour  clock  (0  through  23) 

date;  binary  value  formatted  as  follows: 

Bits 

Meaning 

0-4 

5-8 

9-15 

Day  of  the  month  (1  through  31) 

Month  (1  =  January,  2  =  February,  3  =  March,  and  so  on) 

Year  minus  1980 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  AL  was  OOH  on  call: 

CX  =  time  file  was  last  modified;  format  as  described  above 
DX  =  date  file  was  last  modified;  format  as  described  above 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function  (AL  not  OOH  or  OlH) 

06H  invalid  handle 
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Programmer’s  Notes 

•  Before  the  date  and  time  in  a  file’s  directory  entry  can  be  retrieved  or  changed  with 
Function  57H,  a  handle  must  be  obtained  by  opening  or  creating  the  file  using  one  of 
the  following  functions: 

-  3CH  (Create  File  with  Handle) 

-  3DH  (Open  File  with  Handle) 

-  5AH  (Create  Temporary  File) 

-  5BH  (Create  New  File) 

•  Use  of  Function  57H  to  retrieve  the  date  and  time  of  a  file  is  preferable  to  examining 
the  fields  of  an  open  FCB  directly. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

2AH  (Get  Date) 

2BH  (Set  Date) 

2CH  (Get  Time) 

2DH  (Set  Time) 

Example 

;  Function  57H:  Get /Set  Date/ Time  of  File  ; 

;  long  file_date_time (handle, func,packdate, packtime)  ; 

;  int  handle, func,packdate, packtime/  ; 

;  Returns  a  long  -1  for  all  errors,  otherwise  packs  ; 

;  date  and  time  into  a  long  integer,  ; 

;  date  in  high  word,  time  in  low  word.  ; 

cProc  file_date_time, PUBLIC 
parmW  handle 
parmB  func 
parmW  packdate 
parmW  packtime 
cBegin 

mov  bx, handle 

mov  al,func 

mov  dx, packdate 

mov  cx , packt ime 

mov  ah,57h 

int  21  h 


;  Get  handle. 

;  Get  function:  0  =  read,  1  =  write. 
;  Get  date  (if  present) . 

;  Get  time  (if  present) . 

;  Set  function  code. 

;  Call  MS-DOS. 


(more) 
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dt_ok : 
cEnd 


mov 

ax,  cx 

;  Set  DX:AX  =  date /time, 

;  error . 

jnb 

dt_ok 

;  Branch  if  no  error. 

mov 

ax,  -1 

;  Return  -1  for  errors. 

cwd 

;  Extend  the  -1  into  DX, 

assuming  no 
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Interrupt  21H  (33)  3.0  and  later 

Function  58H  (88) 

Get/Set  Allocation  Strategy 


Function  58H  retrieves  or  sets  the  method  MS-DOS  uses  to  allocate  memory  blocks  for  a 
process  that  issues  a  memory-allocation  request. 

ToCaU 

AH  =  58H 

AL  =  OOH  get  allocation  strategy 

OlH  set  allocation  strategy 

If  AL  =  OlH: 

BX  =  allocation  strategy: 

OOH  use  first  (lowest  available)  block  that  fits 

OlH  use  block  that  fits  best 

02H  use  last  (highest  available)  block  that  fits 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  AL  was  OOH  on  call: 

AX  =  allocation-strategy  code: 

OOH  first  fit 

OlH  best  fit 

02H  last  fit 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function  (AL  not  OOH  or  OlH) 

Programmer’s  Notes 

•  Allocation  strategies  determine  how  MS-DOS  finds  and  allocates  a  block  of  memory 

to  an  application  that  issues  a  memory-allocation  request  with  either  Function  48H 
(Allocate  Memory  Block)  or  Function  4AH  (Resize  Memory  Block). 

The  three  strategies  are  carried  out  as  follows: 

-  First  fit  (the  default):  MS-DOS  works  upward  from  the  lowest  available  block  and 
allocates  the  first  block  it  encounters  that  is  large  enough  to  satisfy  the  request  for 
memory.  This  strategy  is  followed  consistently,  even  if  the  block  allocated  is  much 
larger  than  required. 
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-  Best  fit:  MS-DOS  searches  all  available  memory  blocks  and  then  allocates  the 
smallest  block  that  satisfies  the  request,  regardless  of  its  location  in  the  empty- 
block  chain.  This  strategy  maximizes  the  use  of  dynamically  allocated  memory  at 
a  slight  cost  in  speed  of  allocation. 

-  Last  fit  (the  reverse  of  first  fit):  MS-DOS  works  downward  from  the  highest  avail¬ 
able  block  and  allocates  the  first  block  it  encounters  that  is  large  enough  to  satisfy 
the  request  for  memory.  This  strategy  is  followed  consistently,  even  if  the  block 
allocated  is  much  larger  than  required. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 

error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

48H  (Allocate  Memory  Block) 

4AH  (Resize  Memory  Block) 

Example 

;  Function  58H:  Get /Set  Allocation  Strategy  ; 

;  int  alloc-strategy (func, strategy)  ; 

;  int  func, strategy;  ; 

;  Strategies:  ; 

;  0:  First  fit  ; 

;  1 :  Best  fit  ; 

;  2:  Last  fit  ; 

;  Returns  -1  for  all  errors,  otherwise  ; 

;  returns  the  current  strategy.  ; 


cProc  alloc-strategy, PUBLIC 
parmB  func 
parmW  strategy 
cBegin 

mov  al,func 

mov  bx, strategy 

mov  ah,58h 

int  21 h 

jnb  no_err 

mov  ax,-1 

no_err : 
cEnd 


;  AL  =  get/set  selector. 

;  BX  =  new  strategy  (for  AL  =  01 H) 
/  Set  function  code. 

;  Call  MS-DOS. 

;  Branch  if  no  error. 

;  Return  -1  for  all  errors. 
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Interrupt  21H  (33) 
Function  59H  (89) 

Get  Extended  Error  Information 


3.0  and  later 


Function  59H  returns  extended  error  information,  including  a  suggested  response,  for  the 
function  call  immediately  preceding  it. 

ToCaU 

AH  =  59H 
BX  =00H 

Returns 


OOH 

no  error  encountered 

OlH 

invalid  function  number 

02H 

file  not  found 

03H 

path  not  found 

04H 

too  many  files  open;  no  handles  available 

05H 

access  denied 

06H 

invalid  handle 

07H 

memory  control  blocks  destroyed 

OSH 

insufficient  memory 

09H 

invalid  memory-block  address 

OAH 

invalid  environment 

OBH 

invalid  format 

OCH 

invalid  access  code 

ODH 

invalid  data 

OEH 

reserved 

OFH 

invalid  disk  drive 

lOH 

attempt  to  remove  current  directory 

IIH 

device  not  the  same 

12H 

no  more  files 

13H 

write-protected  disk 

14H 

unknown  unit 

15H 

drive  not  ready 

16H 

invalid  command 

17H 

data  error  based  on  cyclic  redundancy  check  (CRC) 

18H 

length  of  request  structure  invalid 

19H 

seek  error 

lAH 

non-MS-DOS  disk 

IBH 

sector  not  found 
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ICH 

IDH 

lEH 

IFH 

20H 

21H 

22H 

23H 

24H 

25-31H 

32H 

33H 

34H 

35H 

36H 

37H 

38H 

39H 

3AH 

3BH 

3CH 

3DH 

3EH 

3FH 

40H 

41H 

42H 

43H 

44H 

45H 

46H 

47H 

48H 

49-4FH 

50H 

51H 

52H 

53H 

54H 

55H 

56H 

57H 

58H 


printer  out  of  paper 
write  fault 
read  fault 
general  failure 
sharing  violation 
lock  violation 
invalid  disk  change 
FCB  unavailable 
sharing  buffer  exceeded 
reserved 

unsupported  network  request 
remote  machine  not  listening 
duplicate  name  on  network 
network  name  not  found 
network  busy 

device  no  longer  exists  on  network 
net  BIOS  command  limit  exceeded 
error  in  network  adapter  hardware 
incorrect  response  from  network 
unexpected  network  error 
remote  adapt  incompatible 
print  queue  full 
queue  not  full 

not  enough  room  for  print  file 
network  name  deleted 
access  denied 

incorrect  network  device  type 

network  name  not  found 

network  name  limit  exceeded 

net  BIOS  session  limit  exceeded 

temporary  pause 

network  request  not  accepted 

print  or  disk  redirection  paused 

reserved 

file  already  exists 

reserved 

cannot  make  directory 

failure  on  Interrupt  24H  (critical  error) 

out  of  structures 

already  assigned 

invalid  password 

invalid  parameter 

net  write  fault 
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BH  =  error  class: 

OlH  out  of  resource  (such  as  storage) 

02H  temporary  situation,  expected  to  end;  not  an  error 

03H  authorization  problem 

04H  internal  error  in  system  software 

05H  hardware  failure 

06H  system-software  failure,  such  as  missing  or  incorrect 

configuration  files;  not  the  fault  of  the  active  process 
07H  application-program  error 

OSH  file  or  item  not  found 

09H  file  or  item  of  invalid  format  or  type  or  otherwise  unsuitable 

OAH  file  or  item  interlocked 

OBH  drive  contains  wrong  disk,  disk  has  bad  spot,  or  other  problem 

with  storage  medium 
OCH  already  exists 

ODH  unknown 

BL  =  suggested  action: 

OlH  perform  a  reasonable  number  of  retries  before  prompting  user  to 

choose  Abort  or  Ignore  in  response  to  error  message 
02H  perform  a  reasonable  number  of  retries,  with  pauses  between, 

before  prompting  user  to  choose  Abort  or  Ignore  in  response  to 
error  message 

03H  prompt  user  to  enter  corrected  information,  such  as  drive  letter  or 

filename 

04H  clean  up  and  exit  application 

05H  exit  immediately  without  cleanup 

06H  ignore;  informational  error 

07H  prompt  user  to  remove  cause  of  error  (for  example,  change  disks) 

and  then  retry 

CH  =  location  of  error: 

OlH  unknown 

02H  block  device 

03H  network 

04H  serial  device 

05H  memory  related 

Programmer’s  Notes 

•  The  extended  error  codes  returned  by  Function  59H  correspond  to  the  error  values 
returned  in  AX  by  functions  in  MS-DOS  versions  2.0  and  later  that  set  the  carry  flag  on 
error.  Versions  2.x  of  MS-DOS,  however,  provide  a  smaller  set  of  error  codes  (OlH 
through  12H)  than  do  later  versions. 

Thus,  although  Function  59H  itself  is  not  available  in  versions  of  MS-DOS  earlier  than 
3.0,  the  matching  of  error  codes  to  earlier  versions  helps  ensure  downward  com¬ 
patibility.  Function  59H  was  also  designed  to  be  open-ended  so  that  additional  error 
codes  could  be  incorporated  as  needed.  As  a  result,  processes  should  remain  flexible 
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in  their  use  of  this  function  and  should  not  rely  on  a  fixed  set  of  code  numbers  for 
error  detection. 

•  Function  59H  is  useful  in  the  following  situations: 

-  When  MS-DOS  encounters  a  hardware-related  error  condition  and  shifts  control  to 
an  Interrupt  24H  handler  that  has  been  created  by  the  programmer 

-  When  a  handle-related  function  sets  the  carry  flag  to  indicate  an  error  or  when  an 
FCB-related  function  indicates  an  error  by  returning  OFFH  in  the  AL  register 

•  If  a  function  call  results  in  an  error,  Function  59H  returns  meaningful  information 
only  if  it  is  the  next  call  to  MS-DOS.  An  intervening  call  to  another  MS-DOS  function, 
whether  explicit  or  indirect,  causes  the  error  value  for  the  unsuccessful  function  to 
be  lost. 

•  Unlike  most  MS-DOS  functions.  Function  59H  alters  some  registers  that  are  not  used 
to  return  results:  CL,  DX,  SI,  DI,  ES,  and  DS.  These  registers  must  be  preserved  before 
a  call  to  Function  59H  if  their  contents  are  needed  later. 

Related  Functions 

None 

Example 

;♦**********************♦*♦*♦♦***♦♦***********♦***♦*♦*♦*♦****; 

;  Function  59H;  Get  Extended  Error  Information  ; 

;  int  extended-error (err, class,  action, locus)  ; 

;  int  *err;  ; 

;  char  *class, ^action, *locus;  ; 

;  Return  value  is  same  as  err.  ; 

.4;:|e4c:|e:|c4;4c4c:|c]|c:|e4e4c4c*4c3|c«*’ie**4:«***3ic**4c*«:)e******************4:*******; 


cProc 

extended-error, PUBLIC, <ds, si, di> 

parmDP 

perr 

parmDP 

pclass 

parmDP 

paction 

parmDP 

plocus 

cBegin 

push 

ds 

Save  DS. 

xor 

bx,  bx 

mov 

ah,59h 

Set  function  code. 

int 

21h 

Request  error  info  from  MS-DOS 

pop 

ds 

Restore  DS . 

loadDP 

ds, si, perr 

Get  pointer  to  err. 

mov 

[si] , ax 

Store  err. 

loadDP 

ds, si, pclass 

Get  pointer  to  class. 

mov 

[si] ,bh 

Store  class. 

loadDP 

ds, si, paction 

Get  pointer  to  action. 

mov 

[si],bl 

Store  action. 

loadDP 

ds, si, plocus 

Get  pointer  to  locus. 

mov 

[si] , ch 

Store  locus. 

cEnd 
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Interrupt  21H  (33)  3.0  and  later 

Function  5AH  (90) 

Create  Temporary  File 


Function  5AH  uses  the  system  clock  to  create  a  unique  filename,  appends  the  filename  to 
the  specified  path,  opens  the  temporary  file,  and  returns  a  file  handle  that  can  be  used  for 
subsequent  file  operations. 

ToCaU 

AH  =  5AH 

CX  =  file  attribute: 


OOH 

normal  file 

OlH 

read-only  file 

02H 

hidden  file 

04H 

system  file 

DS:DX  =  segment:offset  of  ASCIIZ  path,  ending  with  a  backslash  character  (\)  and 

followed  by  13  bytes  of  memory  (to  receive  the  generated  filename) 

Returns 

If  function  is  successful: 

Carry  flag  is  clear, 

AX  =  handle 

DS:DX  =  segment:offset  of  full  pathname  for  temporary  file 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

03H  path  not  found 

04H  too  many  open  files;  no  handle  available 

05H  access  denied 

Programmer’s  Notes 

•  Only  the  drive  and  path  to  use  for  the  new  file  should  be  specified  in  the  buffer 
pointed  to  by  DS:DX.  The  function  appends  an  eight-character  filename  that  is  gener¬ 
ated  from  the  system  time. 

•  Function  5AH  is  valuable  in  such  situations  as  print  spooling  on  a  network,  where 
temporary  files  are  created  by  many  users. 

•  The  input  string  representing  the  path  for  the  temporary  file  must  be  a  null-termi¬ 
nated  ASCII  string  (ASCIIZ). 

•  In  networking  environments  running  under  MS-DOS  version  3.1  or  later,  MS-DOS 
opens  the  temporary  file  in  compatibility  mode. 
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•  MS-DOS  does  not  delete  temporary  files;  applications  must  do  this  for  themselves. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

16H  (Create  File  with  FCB) 

3CH  (Create  File  with  Handle) 

5BH  (Create  New  File) 

Example 

;  Function  5AH:  Create  Temporary  File  ; 

;  int  create_temp (ppathname, attr)  ; 

;  char  *ppathname;  ; 

;  int  attr;  ; 

;  Returns  -1  if  file  was  not  created,  ; 

;  otherwise  returns  file  handle.  ; 


cProc 

create. 

.temp, PUBLIC, ds 

parmDP 

ppathname 

parmW 

attr 

cBegin 

loadDP 

ds , dx , ppathname 

Get  pointer  to  pathname. 

mov 

cx, attr 

Set  function  code. 

mov 

ah, 5ah 

Ask  MS-DOS  to  make  a  new  file  with 

a  unique  name. 

int 

21h 

Ask  MS-DOS  to  make  a  tmp  file. 

jnb 

o 

ft 

Branch  if  MS-DOS  returned  handle. 

mov 

ax,  -1 

Else  return  -1 . 

ct_ok : 
cEnd 
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Interrupt  21H  (33)  3.0  and  later 

Function  5BH  (91) 

Create  New  File 


Function  5BH  creates  a  new  file  with  the  specified  pathname.  This  function  operates  like 
Function  3CH  (Create  File  with  Handle)  but  fails  if  the  pathname  references  a  file  that 
already  exists. 

ToCaU 


AH 

=  5BH 

CX. 

=  file  attribute: 

OOH 

normal  file 

OlH 

read-only  file 

02H 

hidden  file 

04H 

system  file 

DS:DX  =  segmentioffset  of  ASCIIZ  pathname 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

AX  =  handle 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

03H  path  not  found 

04H  too  many  open  files;  no  handle  available 

05H  access  denied 

50H  file  already  exists 

Programmer's  Notes 

•  The  pathname  must  be  a  null-terminated  ASCII  string  (ASCIIZ). 

•  In  networking  environments  running  under  MS-DOS  version  3.1  or  later,  the  file  is 
opened  in  compatibility  mode.  Function  5BH  fails,  however,  if  the  user  does  not  have 
Create  access  to  the  directory  that  is  to  contain  the  file. 

•  Function  5BH  can  be  used  to  implement  semaphores  in  the  form  of  files  across  a  local 
area  network  or  in  a  multitasking  environment.  If  the  function  succeeds,  the 
semaphore  has  been  acquired.  To  release  the  semaphore,  the  application  simply 
deletes  the  file. 
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•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

16H  (Create  File  with  FCB) 

3CH  (Create  File  with  Handle) 

5AH  (Create  Temporary  File) 

Example 

j  *******************************************  ; 

i  J 

;  Function  5BH:  Create  New  File  '  ; 

i  i 

;  int  create_new (ppathname, attr)  ; 

;  char  *ppathname;  ; 

;  int  attr;  ; 

f  r 

;  Returns  -2  if  file  already  exists,  ; 

;  -1  for  all  other  errors,  ; 

;  otherwise  returns  file  handle.  ; 

f  r 

•************************************************************. 

cProc  create_new, PUBLIC, ds 

parmDP  ppathname 
parmW  attr 
cBegin 

loadDP  ds,dx, ppathname 

mov  cx,attr 

mov  ah, 5bh 

int  21h 

jnb  cn_ok 

mov  bx,-2 

cmp  al,80 

jz  ae_err 

inc  bx 

ae_err : 

mov  ax,bx  ;  Return  error  code. 

cn_ok : 
cEnd 


Get  pointer  to  pathname. 

Get  new  file's  attribute. 

Set  function  code. 

Ask  MS-DOS  to  make  a  new  file. 
Branch  if  MS-DOS  returned  handle. 

Did  file  already  exist? 

Branch  if  so. 

Change  -2  to  -1  . 


1400  The  MS-DOS  Encyclopedia. 


Interrupt  21H  Function  5CH 


Interrupt  21H  (33)  3.0  and  later 

Function  5CH  (92) 

Lock/Unlock  File  Region 


Function  5CH  enables  a  process  running  in  a  networking  or  multitasking  environment  to 

lock  or  unlock  a  range  of  bytes  in  an  open  file. 

ToCaU 

AH  =  5CH 

AL  =  OOH  lock  region 

OlH  unlock  region 

BX  =  handle 

CX:DX  =  4-byte  integer  specifying  beginning  of  region  to  be  locked  or  unlocked 

(offset  in  bytes  from  beginning  of  file) 

SI:DI  =  4-byte  integer  specifying  length  of  region  (measured  in  bytes) 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function  (AL  not  OOH  or  OlH  or  file  sharing  not  loaded) 

06H  invalid  handle 

21H  lock  violation 

24H  sharing  buffer  exceeded 

Programmer's  Notes 

•  A  process  that  either  closes  a  file  containing  a  locked  region  or  terminates  with  the 
file  open  leaves  the  file  in  an  undefined  state.  Under  either  condition,  MS-DOS  might 
handle  the  file  erratically.  If  the  process  can  be  terminated  by  Interrupt  23H  (Control- 
C)  or  24H  (critical  error),  these  interrupts  should  be  trapped  so  that  any  locked 
regions  in  files  can  be  unlocked  before  the  process  terminates. 

•  Locking  a  portion  of  a  file  with  Function  5CH  denies  all  other  processes  both  read 
and  write  access  to  the  specified  region  of  the  file.  This  restriction  also  applies  when 
open  file  handles  are  passed  to  a  child  process  with  Function  4BH  (Load  and  Execute 
Program).  Duplicate  file  handles  created  with  Function  45H  (Duplicate  File  Handle) 
and  46H  (Force  Duplicate  File  Handle),  however,  are  allowed  access  to  locked  regions 
of  a  file  within  the  current  process. 

•  Locking  a  region  that  goes  beyond  the  end  of  a  file  does  not  cause  an  error. 
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•  Function  5CH  is  useful  primarily  in  ensuring  that  competing  programs  or  processes 
do  not  interfere  while  a  record  is  being  updated.  Locking  at  the  file  level  is  provided 
by  the  sharing  parameter  in  Function  3DH  (Open  File  with  Handle). 

•  Function  5CH  can  also  be  used  to  check  the  lock  status  of  a  file.  If  an  attempt  to  lock  a 
needed  portion  of  a  file  fails  and  error  code  21H  is  returned  in  the  AX  register,  the 
region  is  already  locked  by  another  process. 

•  Any  region  locked  with  a  call  to  Function  5CH  must  also  be  unlocked,  and  the  same 
4-byte  integer  values  must  be  used  for  each  operation.  Two  adjacent  regions  of  a  file 
cannot  be  locked  separately  and  then  be  unlocked  with  a  single  unlock  call.  If  the 
region  to  unlock  does  not  correspond  exactly  to  a  locked  region.  Function  5CH 
returns  error  code  21H. 

•  The  length  of  time  needed  to  hold  locks  can  be  minimized  with  the  transaction- 
oriented  programming  model.  This  concept  requires  defining  and  performing  an  up¬ 
date  in  a  uniform  manner:  Assert  lock,  read  data,  change  data,  remove  lock. 

•  If  file  sharing  is  not  loaded,  an  application  receives  a  OlH  (function  number  invalid) 
error  status  when  it  attempts  to  lock  a  file.  An  immediate  call  to  Function  59H  returns 
the  error  locus  as  an  unknown  or  a  serial  device. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 

45H  (Duplicate  File  Handle) 

46H  (Force  Duplicate  File  Handle) 

4BH  (Load  and  Execute  Program)  [EXEC] 

Example 

•  ilti**^t^iltt4tilt‘*****************************************************J 

;  Function  5CH;  Lock/Unlock  File  Region  ; 

;  int  locks (handle, onoff, start, length)  ; 

;  int  handle, onoff;  ; 

;  long  start, length;  ; 

;  Returns  0  if  operation  was  successful,  ; 

;  otherwise  returns  error  code.  ; 

cProc  locks, PUBLIC, <si, di> 

parmW  handle 
parmB  onoff 
parmD  start 
parmD  length 


(more) 
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cBegin 


mov 

al, onoff 

mov 

bx, handle 

les 

dx, start 

mov 

cx,  es 

les 

di, length 

mov 

si,  es 

mov 

ah, 5ch 

int 

21h 

jb 

lk_err 

xor 

ax,  ax 

lk_err ; 
cEnd 


Get  lock/unlock  flag. 

Get  file  handle. 

Get  low  word  of  start. 
Get  high  word  of  start. 
Get  low  word  of  length. 
Get  high  word  of  length. 
Set  function  code. 

Make  lock/unlock  request 
Branch  on  error. 

Return  0  if  no  error. 
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Interrupt  21H  (33)  3.1  and  later 

Function  5EH  (94)  Subfunction  OOH 

Network  Machine  Name/Printer  Setup:  Get  Machine  Name 


If  Microsoft  Networks  is  running,  Function  5EH  Subfunction  OOH  retrieves  the  network 
name  of  the  local  computer. 

ToCaU 

AH  =  5EH 

AL  =  OOH 

DS:DX  =  segment:offset  of  l6-byte  buffer 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

CH  =  validity  of  machine  name: 

OOH  invalid 

nonzero  valid 

CL  =  NETBIOS  number  assigned  to  machine  name 

DS:DX  =  segment:offset  of  ASCIIZ  machine  name 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function;  Microsoft  Networks  not  running 

Programmer’s  Notes 

•  The  NETBIOS  number  in  CL  and  the  name  at  DS:DX  are  valid  only  if  the  value 
returned  in  CH  is  nonzero. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

5FH  (Get/Make  Assign  List  Entry) 

Example 

None 
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Interrupt  21H  (33)  3.1  and  later 

Function  5EH  (94)  Subfunctions  02H  and  03H 

Network  Machine  Name/Printer  Setup:  Set  Printer  Setup; 

Get  Printer  Setup 


Function  5EH  Subfunctions  02H  and  03H  respectively  set  and  get  the  setup  string  that  MS- 
DOS  adds  to  the  beginning  of  a  file  sent  to  a  network  printer. 

ToCaU 

AH  =  5EH 

AL  =  02H  set  printer  setup  string 

03H  get  printer  setup  string 

BX  =  assign-list  index  number  (obtained  with  Function  5FH  Subfunction  02H) 

IfAL  =  02H: 

CX  =  length  of  setup  string  in  bytes  (64  bytes  maximum) 

DS:SI  =  segment:offset  of  ASCII  setup  string 

IfAL  =  03H: 

ES:DI  =  segment:offset  of  64-byte  buffer  to  receive  string 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  AL  was  03H  on  call: 

CX  =  length  of  printer  setup  string  in  bytes 

ES:DI  =  segment:offset  of  ASCII  printer  setup  string 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  subfunction 

Programmer’s  Notes 

•  Function  5EH  Subfunctions  02H  and  03H  enable  multiple  users  on  a  network  to  con¬ 
figure  a  shared  printer  as  required.  The  assign-list  number  is  an  index  to  a  table  that 
identifies  the  printer  as  a  device  on  the  network.  A  process  can  determine  the  assign- 
list  number  for  the  printer  by  using  Function  5FH  Subfunction  02H  (Get  Assign-List 
Entry). 

•  Error  code  OlH  in  the  AX  register  may  indicate  either  that  Microsoft  Networks  is  not 
running  or  that  an  invalid  subfunction  was  selected. 
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•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

5FH  (Get/Make  Assign-List  Entry) 

Example 


Function  5EH  Subfunction  02H: 

Set  Printer  Setup 


int  printer—setup (index, pstring, len) 
int  index; 
char  *pstring; 
int  len; 


Returns  0,  otherwise  returns  -1  for  all  errors. 


cProc  printer-setup, PUBLIC, <ds,  si> 


parmW 

index 

parmDP 

pstring 

parmW 

len 

cBegin 

mov 

bx, index 

loadDP 

ds, si, pstring 

mov 

CX, len 

mov 

ax, 5e02h 

int 

21h 

mov 

al,0 

jnb 

ps_ok 

mov 

al,-1 

ps— ok : 

cbw 

cEnd 

BX  =  index  of  a  net  printer. 
DSiSI  =  pointer  to  string. 

CX  =  length  of  string. 

Set  function  code. 

Set  printer  prefix  string. 
Assume  no  error. 

Branch  if  no  error. 

Else  return  -1 . 
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Interrupt  21H  (33)  3.1  and  later 

Function  5FH  (95)  Subfunction  02H 

Get/Make  Assign-List  Entry:  Get  Assign-List  Entry 


Function  5FH  Subfunction  02H  obtains  the  local  and  remote  (network)  names  of  a  device. 
To  find  the  names,  MS-DOS  uses  the  device’s  user-assigned  index  number  (set  with  Func¬ 
tion  5FH  Subfunction  03H)  to  search  a  table  of  redirected  devices  on  the  network. 
Microsoft  Networks  must  be  running  with  file  sharing  loaded  for  this  subfunction  to  oper¬ 
ate  successfully. 

ToCaU 

AH  =  5FH 

AL  =  02H 

BX  =  assign-list  index  number 

DS:SI  =  segment:offset  of  l6-byte  buffer  for  local  (device)  name 

ES:DI  =  segment:offset  of  128-byte  buffer  to  receive  remote  (network)  name 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

BH  =  device  status: 

OOH  valid  device 

OlH  invalid  device 

BL  =  device  type: 

03H  printer 

04H  drive 

CX  =  user  data 

DS:SI  =  segment:offset  of  ASCIIZ  string  representing  local  device  name 

ES:DI  =  segment:offset  of  ASCIIZ  string  representing  network  name 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function  or  Microsoft  Networks  not  running 

12H  no  more  files 

Programmer’s  Notes 

•  All  strings  returned  by  this  subfunction  are  null-terminated  ASCII  strings  (ASCIIZ). 

•  A  successful  call  to  this  subfunction  destroys  the  contents  of  the  DX  and  BP  registers. 
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•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 

error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

5EH  Subfunction  OOH  (Get  Machine  Name) 

Example 


t 

;  Function  5FH  Subfunction  02H: 

;  Get  Assign-List  Entry 

;  int  get_alist_entry (index, 

;  plocalname,premotename, 

;  puservalue,ptype) 

;  int  index; 

;  char  *plocalname; 

;  char  *premotename; 

;  int  *puservalue; 

;  int  *ptype; 

;  Returns  0  if  the  requested  assign-list  entry  is  found, 
;  otherwise  returns  error  code. 


cProc  get_alist_entry, PUBLIC, <ds, si, di> 


parmW 

index 

parmDP 

plocalname 

parmDP 

premotename 

parmDP 

puservalue 

parmDP 

ptype 

cBegin 

mov 

bx, index  ; 

loadDP 

ds, si, plocalname 

loadDP 

es , di , premotename 

mov 

ax,5f02h  ; 

int 

21h 

jb 

ga_err  ; 

xor 

ax, ax  ; 

loadDP 

ds, si, puservalue 

mov 

[si],cx  ; 

loadDP 

ds, si, ptype 

mov 

bh,0 

mov 

[si],bx  ; 

ga_err : 
cEnd 


Get  list  index. 

;  DS:SI  =  pointer  to  local  name 
;  buffer. 

;  ES:DI  =  pointer  to  remote  name 
;  buffer. 

Set  function  code. 

Get  assign-list  entry. 

Exit  on  error. 

Else  return  0 . 

Get  address  of  uservalue. 

Store  user  value. 

Get  address  of  type. 

Store  device  type  to  type. 
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Interrupt  21H  (33)  3.1  and  later 

Function  5FH  (95)  Subfunction  03H 

Get/Make  Assign-List  Entry:  Make  Assign-List  Entry 


Function  5FH  Subfunction  03H  redirects  a  local  printer  or  disk  drive  to  a  network  device 
and  establishes  an  assign-list  index  number  for  the  redirected  device.  Microsoft  Networks 
must  be  running  with  file  sharing  loaded  for  this  subfunction  to  operate  successfully. 

ToCaU 

AH  =  5FH 

AL  =  03H 

BL  =  device  type: 

03H  printer 

04H  drive 

CX  =  user  data 

DS:SI  =  segment:offset  of  l6-byte  ASCIIZ  local  device  name 
ES:DI  =  segment:offset  of  128-byte  ASCIIZ  remote  (network)  device  name 

and  password  in  the  form 

machine  name\pathname, null, password, null 

For  example: 

string  db  ' \\mymach\wp' , 0, *blibbet ' , 0 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function  or  Microsoft  Networks  not  running 

03H  path  not  found 

05H  access  denied 

OSH  insufficient  memory 

OFH  redirection  paused  on  server 

12H  no  more  files 

Programmer’s  Notes 

•  The  strings  used  by  this  subfunction  must  be  null-terminated  ASCII  strings  (ASCIIZ). 

The  ASCIIZ  string  pointed  to  by  ES:DI  (the  destination,  or  remote,  device)  cannot  be 
more  than  128  bytes  including  the  password,  which  can  be  a  maximum  of  8  charac¬ 
ters.  If  the  password  is  omitted,  the  pathname  must  be  followed  by  2  null  bytes. 
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•  If  BL  =  03H,  the  string  pointed  to  by  DS:SI  must  be  one  of  the  following  printer  names: 
PRN,  LPTl,  LPT2,  or  LPT3.  If  the  call  is  successful,  output  is  redirected  to  a  network 
print  spooler,  which  must  be  named  in  the  destination  string.  For  printer  redirection, 
MS-NET  intercepts  Interrupt  17H  (BIOS  Printer  I/O).  When  redirection  for  a  printer  is 
canceled,  all  printing  is  sent  to  the  first  local  printer  (LPTl). 

If  BL  =  04H,  the  string  pointed  to  by  DS:SI  can  be  a  drive  letter  followed  by  a  colon, 
such  as  E:,  or  it  can  be  a  null  string.  If  the  string  represents  a  valid  drive,  a  successful 
call  redirects  drive  requests  to  the  network  directory  named  in  the  destination  string. 
If  DS:SI  points  to  a  null  string,  MS-DOS  attempts  to  provide  access  to  the  network 
directory  named  in  the  destination  string  without  redirecting  any  device. 

•  Only  printer  and  disk  devices  are  supported  in  MS-DOS  versions  3.1  and  later.  COMl 
and  COM2  are  not  supported  for  network  redirection,  nor  are  the  standard  output  or 
standard  error  devices  supported. 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

5EH  Subfunction  OOH  (Get  Machine  Name) 

Example 


Function  5FH  Subfunction  03H; 

Make  Assign-List  Entry 

int  add-alist—entry (psrcname, pdestname, uservalue, type) 
char  ♦psrcname, *pdestname; 
int  uservalue, type; 

Returns  0  if  new  assign-list  entry  is  made,  otherwise 
returns  error  code. 


cProc  add_alist_entry, PUBLIC, <ds, si, di> 


parmDP 

psrcname 

parmDP 

pdestname 

parmW 

uservalue 

parmW 

type 

cBegin 

mov 

bx, type 

mov 

cx, uservalue 

loadDP 

ds , si , psrcname 

loadDP 

es, di, pdestname 

mov 

ax, 5f03h 

int 

21h 

jb 

aa_err 

xor 

ax,  ax 

aa_err : 
cEnd 


Get  device  type. 

Get  uservalue. 

DS:SI  =  pointer  to  source  name. 

ES:DI  =  pointer  to  destination  name. 
Set  function  code . 

Make  assign-list  entry. 

Exit  if  there  was  some  error. 

Else  return  0. 
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Int  21H  (33)  3.1  and  later 

Function  5FH  (95)  Subfunction  04H 

Get/Make  Assign-List  Entry:  Cancel  Assign-List  Entry 


Function  5FH  Subfunction  04H  cancels  the  redirection  of  a  local  device  to  a  network 
device  previously  established  with  Function  5FH  Subfunction  03H  (Make  Assign-List 
Entry).  Microsoft  Networks  must  be  running  with  file  sharing  loaded  for  this  subfunc¬ 
tion  to  operate  successfully. 

ToCaU 

AH  =5FH 

AL  =  04H 

DS:SI  =  segment:offset  of  ASCIIZ  device  name  or  path 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function  or  Microsoft  Networks  not  running 

03H  path  not  found 

05H  access  denied 

OSH  insufficient  memory 

OFH  redirection  paused  on  server 

12H  no  more  files 

Programmer’s  Notes 

•  The  string  pointed  to  by  DS:SI  must  be  a  null-terminated  ASCII  string  (ASCIIZ).  This 

string  can  be  any  one  of  the  following: 

-  The  letter,  followed  by  a  colon,  of  a  redirected  local  drive.  This  function  restores 
the  drive  letter  to  its  original,  physical  meaning. 

-  The  name  of  a  redirected  printer:  PRN,  LPTl,  LPT2,  LPT3,  or  its  machine-specific 
equivalent.  This  function  restores  the  printer  name  to  its  original,  physical  meaning 
at  the  local  workstation. 

-  A  string,  beginning  with  two  backslashes  (\  \)  followed  by  the  name  of  a  network 
directory.  This  function  terminates  the  connection  between  the  local  workstation 
and  the  directory  specified  in  the  string. 
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•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Function 

5EH  Subfunction  OOH  (Get  Machine  Name) 

Example 

.«***:i::ic«*:K**Hc**4c*«:ic**:ic«**4:***«*«4c«:ic4!4:**4c*4:4i*4E*********««****:ie; 
r  } 

;  Function  5FH  Subfunction  04H:  ; 

;  Cancel  Assign-List  Entry  ; 

f  r 

;  int  cancel_alist_entry  (psrcname)  ; 

;  char  *ps rename;  ; 

/  / 

;  Returns  0  if  assignment  is  canceled,  otherwise  returns  ; 

;  error  code.  ; 

r  f 

•  **4:*:ic****************:)«*****4:«**««!ic**3ic*3|c*iic***«*«4c********«***; 

cProc  cancel_alist_entry, PUBLIC, <ds, si> 

parmDP  psrcname 
cBegin 

loadDP  ds, si, psrcname 
mov  ax,5f04h 
int  21h 

jb  ca_err 

xor  ax, ax 

ca_err : 
cEnd 


;  DS:SI  =  pointer  to  source  name. 
;  Set  function  code. 

;  Cancel  assign-list  entry. 

;  Exit  on  error. 

;  Else  return  0. 
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Interrupt  21H  (33)  3.0  and  later 

Function  62H  (98) 

Get  Program  Segment  Prefix  Address 


Function  62H  gets  the  segment  address  of  the  program  segment  prefix  (PSP)  for  the  cur¬ 
rent  process. 

ToCaU 

AH  =  62H 

Returns 

BX  =  segment  address  of  PSP  for  current  process 

Programmer’s  Notes 

•  The  PSP  is  constructed  by  MS-DOS  at  the  base  of  the  memory  allocated  for  a  .COM 
or  .EXE  program  being  loaded  into  memory  by  the  EXEC  function,  4BH  (Load  and 
Execute  Program).  The  PSP  is  lOOH  bytes  and  contains  information  useful  to  an  ex¬ 
ecuting  program,  including 

-  The  command  tail 

-  Default  file  control  blocks  (FCBs) 

-  A  pointer  to  the  program’s  environment  block 

-  Previous  addresses  for  MS-DOS  Control-C,  critical  error,  and  terminate  handlers 

•  Function  59H  (Get  Extended  Error  Information)  provides  further  information  on  any 
error — in  particular,  the  code,  class,  recommended  corrective  action,  and  locus  of 
the  error. 

Related  Functions 
None 
Example 


Function  62H:  Get  Program  Segment  Prefix  Address 
int  get_psp() 

Returns  PSP  segment. 

*************;¥*******************  ***********^^4^************** 


(more) 
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cProc  get_psp, PUBLIC 
cBegin 

mov  ah, 62h 

int  21 h 

mov  ax,bx 

cEnd 


;  Set  function  code. 
;  Get  PSP  address. 

;  Return  it  in  AX . 
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Interrupt  21H  (33) 
Function  63H  (99) 

Get  Lead  Byte  Table 


Function  63H,  available  only  in  MS-DOS  version  2.25,  includes  three  subfunctions  that 
support  2-byte-per-character  alphabets  such  as  Kanji  and  Hangeul  (Japanese  and  Korean 
characters  sets).  Subfunction  OOH  obtains  the  address  of  the  legal  lead  byte  ranges  for  the 
character  sets;  Subfunctions  OlH  and  02H  set  or  obtain  the  value  of  the  interim  console 
flag,  which  determines  whether  interim  characters  are  returned  by  certain  console  system 
calls. 

ToCaU 


AH  =  63H 

AL  =  OOH 

get  lead  byte  table  address 

OlH 

set  or  clear  interim  console  flag 

02H 

get  interim  console  flag 

IfAL  =  01H: 

DL  =  interim  console  flag: 

OOH 

clear 

OlH 

set 

Returns 

If  function  is  successful: 

Carry  flag  is  clear. 

If  AL  was  OOH  on  call: 

DS:SI  =  segment:offset  of  lead  byte  table 

If  AL  was  02H  on  call: 

DL  =  value  of  interim  console  flag 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 

OlH  invalid  function 

Programmer’s  Notes 

•  Function  63H  does  not  necessarily  preserve  any  registers  other  than  SS:SP,  so  register 
values  should  be  saved  before  a  call  to  this  function.  To  avoid  saving  registers  repeat¬ 
edly,  a  process  can  either  copy  the  table  or  save  the  pointer  to  the  table  for  later  use. 
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•  The  lead  byte  table  contains  pairs  of  bytes  that  represent  the  inclusive  boundary 
values  for  the  lead  bytes  of  the  specified  alphabet.  Because  of  the  way  bytes  are  or¬ 
dered  by  the  8086  microprocessor  family,  the  values  must  be  read  as  byte  values,  not 
as  word  values. 

•  If  the  interim  console  flag  is  set  (DL  =  OlH)  by  a  program  through  a  call  to  Function 
63H,  the  following  functions  return  interim  character  information  on  request: 

-  07H  (Character  Input  Without  Echo) 

-  08H  (Unfiltered  Character  Input  Without  Echo) 

-  OBH  (Check  Keyboard  Status) 

-  OCH  (Flush  Buffer,  Read  Keyboard),  if  Function  07H  or  08H  is  requested  in  AL 

Related  Functions 
None 
Example 

.iiiittHtitLHiHi:it^idti^iiti^iiti***iti*******************************************; 

;  Function  63H:  Get  Lead  Byte  Table  ; 

;  char  far  *get— lead  byte_table ( )  ; 

;  Returns  far  pointer  to  table  of  lead  bytes  for  multibyte  ; 

;  characters.  Will  work  only  in  MS-DOS  2.25!  ; 

.  ****♦*******♦**♦*****♦***♦♦*♦**♦♦♦******♦*♦*♦♦*♦****♦*♦*****; 
cProc  get— lead  byte— table, PUBLIC, <ds, si> 


cBegin 

mov 

ax, 6300h 

;  Set  function  code. 

int 

21h 

;  Get  lead  byte  table. 

mov 

dx,  ds 

;  Return  far  pointer  in  DX:AX 

cEnd 

mov 

ax,  si 
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Interrupt  22H  (34)  1.0  and  later 

Terminate  Routine  Address 


The  machine  interrupt  vector  for  Interrupt  22H  (memory  locations  0000:0088H  through 
0000:008BH)  contains  the  address  of  the  routine  that  receives  control  when  the  currently 
executing  program  terminates  by  means  of  Interrupt  20H,  Interrupt  27H,  or  Interrupt  21H 
Function  OOH,  31H,  or  4CH. 

ToCaU 

This  interrupt  should  never  be  issued  directly. 

Returns 

Nothing 

Programmer’s  Note 

•  The  address  in  this  vector  is  copied  into  offsets  OAH  through  ODH  of  the  program 
segment  prefix  (PSP)  when  a  program  is  loaded  but  before  it  begins  executing.  The 
address  is  restored  from  the  PSP  (in  case  it  was  modified  by  the  application)  as  part  of 
MS-DOS’s  termination  handling. 

Example 

None 
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Interrupt  23H  (35)  1.0  and  later 

Control-C  Handler  Address 


The  machine  interrupt  vector  for  Interrupt  23H  (memory  locations  0000:008CH  through 

0000:008FH)  contains  the  address  of  the  routine  that  receives  control  when  a  Control-C 

(also  Control-Break  on  IBM  PC  compatibles)  is  detected  during  any  character  I/O  function 

and,  if  the  Break  flag  is  on,  during  most  other  MS-DOS  function  calls. 

To  Call 

This  interrupt  should  never  be  issued  directly. 

Returns 

Nothing 

Programmer’s  Notes 

•  The  address  in  this  vector  is  copied  into  offsets  OEH  through  IIH  of  the  program 
segment  prefix  (PSP)  when  a  program  is  loaded  but  before  it  begins  executing.  The 
address  is  restored  from  the  PSP  (in  case  it  was  modified  by  the  application)  as  part  of 
MS-DOS’s  termination  handling. 

•  The  initialization  code  for  an  application  can  use  Interrupt  21H  Function  25H  (Set 
Interrupt  Vector)  to  reset  the  Interrupt  23H  vector  to  point  to  its  own  routine  for 
Control-C  handling.  By  installing  its  own  Control-C  handler,  the  program  can  avoid 
being  terminated  as  a  result  of  keyboard  entry  of  a  Control-C  or  Control-Break. 

•  When  a  Control-C  is  detected  and  the  program’s  Interrupt  23H  handler  receives  con¬ 
trol,  MS-DOS  sets  all  registers  to  the  original  values  they  had  when  the  function  call 
that  is  being  interrupted  was  made.  The  program’s  interrupt  handler  can  then  do  any 
of  the  following: 

-  Set  a  local  flag  for  later  inspection  by  the  application  (or  take  any  other  appropriate 
action)  and  then  perform  a  return  from  interrupt  (IRET)  to  return  control  to  MS- 
DOS.  (All  registers  must  be  preserved.)  The  MS-DOS  function  in  progress  is  then 
restarted  and  proceeds  to  completion,  and  control  finally  returns  to  the  application 
in  the  normal  manner. 

-  Take  appropriate  action  and  then  perform  a  far  return  (RET  FAR)  to  give  control 
back  to  MS-DOS.  MS-DOS  uses  the  state  of  the  carry  flag  to  determine  what  action 
to  take:  If  the  carry  flag  is  set,  the  application  is  terminated;  if  the  carry  flag  is  clear, 
the  application  continues  in  the  normal  manner. 

-  Retain  control  by  transferring  to  an  error-handling  routine  within  the  application 
and  then  resume  execution  or  take  other  appropriate  action,  never  performing  a 
RET  FAR  or  IRET  to  end  the  interrupt-handling  sequence.  This  option  causes  no 
harm  to  the  system. 

•  Any  MS-DOS  function  call  can  be  used  within  the  body  of  an  Interrupt  23H  handler. 

Example 

None 
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Interrupt  24H  (36)  1.0  and  later 

Critical  Error  Handler  Address 


The  machine  interrupt  vector  for  Interrupt  24H  (memory  locations  0000:0090H  through 

0000:0093H)  contains  the  address  of  the  routine  that  receives  control  when  a  critical  error 

(usually  a  hardware  error)  is  detected. 

To  Call 

This  interrupt  should  never  be  issued  directly. 

Returns 

Nothing 

Programmer’s  Notes 

•  The  address  of  this  vector  is  copied  into  offsets  12H  through  15H  of  the  program 
segment  prefix  (PSP)  when  a  program  is  loaded  but  before  it  begins  executing.  The 
address  is  restored  from  the  PSP  (in  case  it  was  modified  by  the  application)  as  part 
of  MS-DOS’s  termination  handling. 

•  On  entry  to  the  critical  error  interrupt  handler,  bit  7  of  register  AH  is  clear  (0)  if  the 
error  was  a  disk  I/O  error;  otherwise,  it  is  set  (1).  BP:SI  contains  the  address  of  a 
device-header  control  block  from  which  additional  information  can  be  obtained. 
Interrupts  are  disabled.  MS-DOS  sets  up  the  registers  for  a  retry  operation  and  one 
of  the  following  error  codes  is  in  the  lower  byte  of  the  DI  register  (the  upper  byte 
is  undefined): 


Code 

Meaning 

OOH 

Write-protect  error 

OlH 

Unknown  unit 

02H 

Drive  not  ready 

03H 

Unknown  command 

04H 

Data  error  (bad  CRC) 

05H 

Bad  request  structure  length 

06H 

Seek  error 

07H 

Unknown  media  type 

OSH 

Sector  not  found 

09H 

Printer  out  of  paper 

OAH 

Write  fault 

OBH 

Read  fault 

OCH 

General  failure 

OFH 

Invalid  disk  change 

These  are  the  same  error  codes  returned  by  the  device  drivers  in  the  request  header. 
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•  On  a  disk  error,  MS-DOS  retries  the  operation  three  times  before  transferring  to  the 
Interrupt  24H  handler. 

•  On  entry  to  the  Interrupt  24H  handler,  the  stack  is  set  up  as  follows: 


Flags 

CS 

IP 

ES 

DS 

BP 

DI 

SI 

DX 

CX 

BX 

AX 

Flags 

CS 

IP 

Flags  and  CS:IP  pushed  on  stack 
by  original  Interrupt  21H  call 


SP  on  entry  to  Interrupt  21H  handler 


Registers  at  point  of 
original  Interrupt  21H  call 


Return  address  hrom 
Interrupt  24H  handler 


SP  on  entry  to  Interrupt  24H  handler 


•  Interrupt  24H  handlers  must  preserve  the  SS,  SP,  DS,  ES,  BX,  CX,  and  DX  registers. 
Only  Interrupt  21H  Functions  OlH  through  OCH,  30H,  and  59H  can  be  used  by  an 
Interrupt  24H  handler;  other  calls  will  destroy  the  MS-DOS  stack  and  its  ability  to  re¬ 
try  or  ignore  an  error. 


1420  The  MS-DOS  Encyclopedia 


Interrupt  24H 


•  Before  issuing  a  RETURN  FROM  INTERRUPT  (IRET),  the  Interrupt  24H  handler 
should  place  an  action  code  in  AL  that  will  be  interpreted  by  MS-DOS  as  follows: 


Code  Meaning 

OOH  Ignore  error. 

OlH  Retry  operation. 

02H  Terminate  program  through  Interrupt  23H. 

03H  Fail  system  call  in  progress  (versions  3.1  and  later). 

•  If  an  Interrupt  24H  routine  returns  to  the  user  program  rather  than  to  MS-DOS,  it 
must  restore  the  user  program’s  registers,  removing  all  but  the  last  three  words  from 
the  stack,  and  issue  an  IRET.  Control  returns  to  the  instruction  immediately  following 
the  Interrupt  21H  function  call  that  resulted  in  an  error.  This  leaves  MS-DOS  in  an 
unstable  state  until  a  call  is  made  to  an  Interrupt  21H  function  higher  than  OCH. 

Example 

None 
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Interrupt  25H  (37)  1.0  and  later 

Absolute  Disk  Read 


Interrupt  25H  provides  direct  linkage  to  the  MS-DOS  BIOS  module  to  read  data  from  a  logi¬ 
cal  disk  sector  into  a  specified  memory  location. 

To  Call 

AL  =  drive  number  (0  =  drive  A,  1  =  drive  B,  and  so  on) 

CX  =  number  of  sectors  to  read 

DX  =  starting  relative  (logical)  sector  number 

DS:BX  =  segment:offset  of  disk  transfer  area  (DTA) 

Returns 

If  operation  is  successful: 

Carry  flag  is  clear. 

If  operation  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code 

Programmer’s  Notes 

•  Interrupt  25H  might  destroy  all  registers  except  the  segment  registers. 

•  When  Interrupt  25H  returns,  the  CPU  flags  originally  pushed  onto  the  stack  by  the 
INT  25H  instruction  are  still  on  the  stack.  The  stack  must  be  cleared  by  a  POPF  or 
ADD  SP,2  instruction  to  prevent  uncontrolled  stack  growth  and  to  make  accessible 
any  other  values  that  were  pushed  onto  the  stack  before  the  call  to  Interrupt  25H. 

•  Logical  sector  numbers  are  zero  based  and  are  obtained  by  numbering  each  disk 
sector  sequentially  from  track  0,  head  0,  sector  1  and  continuing  until  the  last  sector 
on  the  disk  is  counted.  The  head  number  is  incremented  before  the  track  number. 
Because  of  interleaving,  logically  adjacent  sectors  might  not  be  physically  adjacent  for 
some  types  of  disks. 

•  The  lower  byte  of  the  error  code  (AL)  is  the  same  error  code  that  is  returned  in  the 
lower  byte  of  DI  when  an  Interrupt  24H  is  issued.  The  upper  byte  (AH)  contains  one 
of  the  following  codes: 


Code 

Meaning 

80H 

Device  failed  to  respond 

40H 

Seek  operation  failure 

20H 

Controller  failure 

(more) 
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Code 

Meaning 

lOH 

Data  error  (bad  CRC) 

OSH 

Direct  memory  access  (DMA)  failure 

04H 

Requested  sector  not  found 

03H 

Write-protect  fault 

02H 

Bad  address  mark 

OlH 

Bad  command 

•  Warning:  Interrupt  25H  bypasses  the  MS-DOS  file  system.  This  function  must  be 
used  with  caution  to  avoid  damaging  the  disk  structure. 

Example 

; 

;  Interrupt  25H;  Absolute  Disk  Read  ; 

i 

;  Read  logical  sector  1  of  drive  A  into  the  memory  area  ; 

;  named  buff.  (On  most  MS-DOS  floppy  disks,  this  sector  ; 

;  contains  the  beginning  of  the  file  allocation  table.)  ; 


mov 

al,0 

;  Drive  A. 

mov 

cx,  1 

;  Number  of  sectors. 

mov 

dx,1 

/  Beginning  sector  number 

mov 

bx,seg  buff 

;  Address  of  buffer. 

mov 

ds,bx 

mov 

bx, offset  buff 

int 

25h 

;  Request  disk  read. 

jc 

error 

;  Jump  if  read  failed. 

add 

sp,  2 

;  Clear  stack. 

error:  ;  Error  routine  goes  here. 


buff  db  512  dup  (?) 
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Absolute  Disk  Write 


1.0  and  later 


Interrupt  26H  provides  direct  linkage  to  the  MS-DOS  BIOS  module  to  write  data  from  a 
specified  memory  buffer  to  a  logical  disk  sector. 


ToCaU 

AL 

CX 

px 

D^:BX 


=  drive  number  (0  =^drive  A,  1  =  drive<B,  and  so  on) 
=  number  of  sectors  to  write 
=  starting  relative  (logical)  sector  number 
=  segment:offset  of  disk  transfer  area  (DTA) 


Returns 


If  operation  is  successful: 


Carry  flag  is  clear. 


If  operation  is  not  successful: 
Carry  flag  is  set. 

AX  =  error  code 


Programmer's  Notes 

•  when  Interrupt  26H  returns,  the  CPU  flags  originally  pushed  onto  the  stack  by  the 
INT  26H  instruction  are  still  on  the  stack.  The  stack  must  be  cleared  by  a  POPF  or 
ADD  SP,2  instruction  to  prevent  uncontrolled  stack  growth  and  to  make  accessible 
any  other  values  that  were  pushed  on  the  stack  before  the  call  to  Interrupt  26H. 

•  Logical  sector  numbers  are  zero  based  and  are  obtained  by  numbering  each  disk  sec¬ 
tor  sequentially  from  track  0,  head  0,  sector  1  and  continuing  until  the  last  sector  on 
the  disk  is  counted.  The  head  number  is  incremented  before  the  track  number. 
Because  of  interleaving,  logically  adjacent  sectors  might  not  be  physically  adjacent  for 
some  types  of  disks. 

•  The  lower  byte  of  the  error  code  (AL)  is  the  same  error  code  that  is  returned  in  the 
lower  byte  of  DI  when  an  Interrupt  24H  is  issued.  The  upper  byte  (AH)  contains  one 
of  the  following  codes: 


Code 

Meaning 

80H 

Device  failed  to  respond 

40H 

Seek  operation  failure 

20H 

Controller  failure 

lOH 

Data  error  (bad  CRC) 

(more) 
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Code 

Meaning 

OSH 

Direct  memory  access  (DMA)  failure 

04H 

Requested  sector  not  found 

03H 

Write-protect  fault 

02H 

Bad  address  mark 

OlH 

Bad  command 

•  Warning:  Interrupt  26H  bypasses  the  MS-DOS  file  system.  This  function  must  be 
used  with  caution  to  avoid  damaging  the  disk  structure. 

Example 

; 

;  Interrupt  26H:  Absolute  Disk  Write  ; 

;  Write  the  contents  of  the  memory  area  named  buff  ; 

;  into  logical  sector  3  of  drive  C.  ; 

>  f 

;  WARNING:  Verbatim  use  of  this  code  could  damage  ; 

;  the  file  structure  of  the  fixed  disk.  It  is  meant  ; 

;  only  as  a  general  guide.  There  is,  unfortunately,  ; 

;  no  way  to  give  a  really  safe  example  of  this  interrupt.  ; 

f  t 


mov 

al,2 

mov 

cx,  1 

mov 

dx,  3 

mov 

bx, seg  buff 

mov 

ds,bx 

mov 

bx, offset  buff 

int 

26h 

jc 

error 

add 

sp,2 

error : 


buff  db  512  dup  (?) 


;  Drive  C . 

;  Number  of  sectors. 

;  Beginning  sector  number. 
;  Address  of  buffer. 

;  Request  disk  write. 

;  Jump  if  write  failed. 

;  Clear  stack. 


;  Error  routine  goes  here. 


;  Data  to  be  written  to  disk. 
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Interrupt  27H  (39)  1.0  and  later 

Terminate  and  Stay  Resident 


Interrupt  27H  terminates  execution  of  the  currently  executing  program  but  reserves  part 
or  all  of  its  memory  so  that  it  will  not  be  overlaid  by  the  next  transient  program  to  be 
loaded. 

To  Call 

DX  =  offset  of  last  byte  plus  1  (relative  to  the  program  segment  prefix,  or  PSP)  of  program 
to  be  protected 
CS  =  segment  address  of  PSP 

Returns 

Nothing 

Programmer’s  Notes 

•  In  response  to  an  Interrupt  27H  call,  MS-DOS  takes  the  following  actions: 

-  Restores  the  termination  vector  (Interrupt  22H)  from  PSPiOOOAH. 

-  Restores  the  Control-C  vector  (Interrupt  23H)  from  PSPiOOOEH. 

-  With  MS-DOS  versions  2.0  and  later,  restores  the  critical  error  handler  vector  (Inter¬ 
rupt  24H)  from  PSP:0012H. 

-  Transfers  to  the  termination  handler  address. 

•  If  the  program  is  returning  to  COMMAND.COM  rather  than  to  another  program, 
control  transfers  first  to  COMMAND.COM’s  resident  portion,  which  reloads 
COMMAND.COM’s  transient  portion  (if  necessary)  and  passes  it  control.  If  a  batch 
file  is  in  progress,  the  next  line  of  the  file  is  then  fetched  and  interpreted;  otherwise, 
a  prompt  is  issued  for  the  next  user  command. 

•  This  interrupt  is  typically  used  to  allow  user-written  drivers  or  interrupt  handlers  to 
be  loaded  as  ordinary  .COM  or  .EXE  programs  and  then  remain  resident.  Subsequent 
entrance  to  the  code  is  by  means  of  a  hardware  or  software  interrupt. 

•  The  maximum  amount  of  memory  that  can  be  reserved  with  this  interrupt  is  64  KB. 
Therefore,  Interrupt  27H  should  be  used  only  for  applications  that  must  run  under 
MS-DOS  versions  1.x. 

With  versions  2.0  and  later,  the  preferred  method  to  terminate  and  stay  resident  is 
to  use  Interrupt  21H  Function  31H,  which  allows  the  program  to  reserve  more  than 
64  KB  of  memory  and  does  not  require  CS  to  contain  the  PSP  address. 

•  Interrupt  27H  should  not  be  called  by  .EXE  programs  that  are  loaded  into  the  high 
end  of  memory  (that  is,  linked  with  the  /HIGH  switch),  because  this  would  reserve 
the  memory  that  is  ordinarily  used  by  the  transient  portion  of  COMMAND.COM.  If 
COMMAND.COM  cannot  be  reloaded,  the  system  will  fail. 


1426  The  MS-DOS  Encyclopedia 


Interrupt  27H 


•  Because  execution  of  Interrupt  27H  results  in  the  restoration  of  the  terminate  routine 
(Interrupt  22H),  Control-C  (Interrupt  23H),  and  critical  error  (Interrupt  24H)  vectors, 
it  cannot  be  used  to  permanently  install  a  user-written  critical  error  handler. 

•  Interrupt  27H  does  not  work  correctly  when  DX  contains  values  in  the  range  FFFIH 
through  FFFFH.  In  this  case,  MS-DOS  discards  the  high  bit  of  the  contents  of  DX, 
resulting  in  32  KB  less  resident  memory  than  was  actually  requested  by  the  program. 

Example 

-***  ********:t^:ti:ti*************  *************************  . 

;  Interrupt  27H:  Terminate  and  Stay  Resident  ; 

;  Exit  and  stay  resident,  reserving  enough  memory  ; 

;  to  protect  the  program's  code  and  data.  ; 

f***********************************************iti*:tii^it:iti^i:i:iii:Hiii:4i:itHiHt*. 

Start: 


mov  dx, offset  pgm_end  ;  DX  =  bytes  to  reserve, 

int  27h  ;  Terminate,  stay  resident. 


pgiTL_end  equ  $ 

end  start 
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Interrupt  2FH  (47)  2.0  and  later 

Multiplex  Interrupt 


Interrupt  2FH  with  AH  =  OlH  submits  a  file  to  the  print  spooler,  removes  a  file  from  the 
print  spooler’s  queue  of  pending  files,  or  obtains  the  status  of  the  printer.  Other  values  for 
AH  are  used  by  various  MS-DOS  extensions,  such  as  APPEND. 

ToCaU 


AH 

=  01H 

print  spooler  call 

AL 

=  00H 

get  installed  status 

OlH 

submit  file  to  be  printed 

02H 

remove  file  from  print  queue 

03H 

cancel  all  files  in  queue 

04H 

hold  print  jobs  for  status  read 

05H 

end  hold  for  status  read 

IfAL  is  OlH: 

DS:DX  =  segmentioffset  of  packet  address 

IfALis02H: 

DS:DX  =  segment:offset  of  ASCIIZ  file  specification 

Returns 

If  operation  is  successful: 

Carry  flag  is  clear. 

If  AL  was  OOH  on  call: 

AL  =  status: 

OOH  not  installed,  OK  to  install 

OlH  not  installed,  not  OK  to  install 

FFH  installed 

If  AL  was  04H  on  call: 

DX  =  error  count 

DS:SI  =  segment:offset  of  print  queue 

If  operation  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code: 


OlH 

function  invalid 

02H 

file  not  found 

03H 

path  not  found 

(more) 
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04H  too  many  open  files 
05H  access  denied 

OSH  queue  full 

09H  spooler  busy 

OCH  name  too  long 

OFH  drive  invalid 

Programmer’s  Notes 

•  For  Subfunction  OlH,  the  packet  consists  of  5  bytes.  The  first  byte  contains  the  level 
(must  be  zero),  the  next  4  bytes  contain  the  doubleword  address  (segment  and  offset) 
of  an  ASCIIZ  file  specification.  (The  filename  cannot  contain  wildcard  characters.) 

If  the  file  exists,  it  is  added  to  the  end  of  the  print  queue. 

•  For  Subfunction  02H,  wildcard  characters  (♦and  ?)  are  allowed  in  the  file  specification, 
making  it  possible  to  delete  multiple  files  from  the  print  queue  with  one  call. 

•  For  Subfunction  04H,  the  address  returned  for  the  print  queue  points  to  a  series  of 
filename  entries.  Each  entry  in  the  queue  is  64  bytes  and  contains  an  ASCIIZ  file 
specification.  The  first  file  specification  in  the  queue  is  the  one  currently  being 
printed.  The  last  slot  in  the  queue  has  a  null  (zero)  in  the  first  byte. 

Example 

None 
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Appendix  A 
MS-DOS  Version  3-3 


For  the  MS-DOS  user,  version  3.3  incorporates  some  long-awaited  capabilities,  runs  faster 
in  places,  and  requires  about  9  KB  more  memory  than  version  3.2.  Its  most  apparent 
changes,  however,  relate  to  a  new,  more  flexible  method  of  supporting  different  national 
languages.  For  the  MS-DOS  programmer,  version  3.3  offers  several  enhancements  in  the 
areas  of  file  management  and  internationalization  support.  This  appendix  offers  an  over¬ 
view  of  these  new  features. 


Version  3.3  User  Considerations 

MS-DOS  version  3.3  has  introduced  several  changes  at  the  user  level.  A  new  external  com¬ 
mand,  FASTOPEN,  speeds  up  the  filing  system  by  keeping  file  locations  in  memory.  A  new 
batch  command,  CALL,  lets  a  batch  file  call  another  batch  file  and,  when  that  file  termi¬ 
nates,  continue  execution  with  the  next  command  in  the  original  batch  file  rather  than 
return  to  MS-DOS  as  in  previous  versions.  Two  commands  previously  present  only  in 
PC-DOS,  COMP  and  SELECT,  have  been  added  to  MS-DOS.  Five  commands  have  addi¬ 
tional  capabilities:  APPEND,  ATTRIB,  BACKUP,  FDISK,  and  MODE.  In  addition,  the  TIME 
and  DATE  commands  automatically  set  the  CMOS  clock-calendar  on  the  IBM  PC/AT  and 
PS/2  machines,  making  use  of  the  separate  SETUP  program  unnecessary  for  these  func¬ 
tions.  Changes  to  the  national  language  support  involve  four  new  commands,  three  new 
options  to  the  MODE  command,  two  new  or  modified  system  information  files,  and  two 
new  device  drivers.  Each  of  these  new  or  modified  commands  is  discussed  individually 
below. 

The  FASTOPEN  command 

when  MS-DOS  searches  for  a  program  file,  it  searches  each  directory  specified  in  the 
PATH  search  path.  A  lengthy  path  that  has  to  search  many  levels  of  a  directory  structure 
can  make  this  a  slow  process.  The  FASTOPEN  command  loads  a  terminate-and-stay- 
resident  (TSR)  program  that  caches  the  locations  of  the  most  recently  accessed  directories 
and  files  on  one  or  more  fixed  disks  in  the  system.  The  number  of  files  and  directories  to 
be  cached  is  under  the  user’s  control;  the  default  is  10.  When  it  needs  a  file,  MS-DOS  looks 
first  in  the  FASTOPEN  list;  if  the  file  is  found  in  the  list,  MS-DOS  can  bypass  inspection  of 
the  search  path  specified  by  PATH.  When  the  FASTOPEN  list  is  filled  and  a  new  file  is 
opened,  the  new  file  replaces  the  least  recently  used  file  on  the  FASTOPEN  list. 

The  improvement  in  file-system  performance  depends  on  the  number  of  open  files  and 
the  frequency  of  file  access.  The  FASTOPEN  command  can  be  entered  only  once  during  a 
session  and,  if  desired,  can  be  placed  in  the  AUTOEXEC.BAT  file. 
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The  FASTOPEN  command  has  two  parameters: 

FASTOPEN  drive'X=entries][ . . .] 

The  drive  parameter  is  the  drive  letter,  followed  by  a  colon,  of  a  fixed  disk  for  which 
FASTOPEN  is  to  keep  track  of  the  most  recently  accessed  directories  and  files.  More  than 
one  drive  can  be  specified  by  separating  the  drive  identifiers  with  spaces;  the  maximum  is 
four  drives.  A  drive  associated  with  a  JOIN,  SUBST,  or  ASSIGN  command  cannot  be  speci¬ 
fied,  nor  can  a  drive  assigned  to  a  network. 

The  optional  entries  parameter  is  the  number  of  directory  entries  FASTOPEN  is  to  keep  in 
memory.  The  value  of  entries  can  be  from  10  through  999;  the  default  is  34.  If  more  than 
one  entries  value  is  specified,  their  sum  cannot  exceed  999.  Each  entry  subtracts  40  bytes 
from  the  RAM  normally  available  to  run  application  programs. 

Examples:  The  following  command  tells  MS-DOS  to  keep  track  of  the  last  50  directories 
and  files  on  drive  C: 

OFASTOPEN  C:=50  <Enter> 

The  next  command  tells  MS-DOS  to  keep  track  of  the  last  34  files  on  drives  C  and  D: 

C>FASTOPEN  C:  D:  <Enter> 

Chaages  to  batch-file  processing 

Batch-file  processing  also  gains  power  in  MS-DOS  version  3.3.  The  user  can  now  suppress 
the  echo  of  all  batch  commands  and  call  one  batch  file  from  another  without  terminating 
the  first  batch  file. 


With  MS-DOS  version  3.3,  any  line  in  a  batch  file  preceded  by  @  is  not  echoed  to  the 
screen  when  the  batch  file  is  executed. 


CALL 

A  batch  file  no  longer  needs  to  load  an  additional  copy  of  COMMAND.COM  in  order  to 
execute  another  batch  file  and  return  control  to  the  calling  batch  file.  The  CALL  command 
executes  a  batch  file  and  returns  to  the  next  command  in  the  calling  batch  file. 

CALL  commands  can  be  nested.  If  an  exit  condition  is  provided,  a  batch  file  can  even  call 
itself;  however,  the  input  or  output  of  a  called  batch  file  cannot  be  redirected  or  piped. 

The  CALL  command  has  two  parameters: 

CALL  batch-file  [parameters] 

The  batch-file  parameter  is  the  name  of  the  batch  file  to  be  executed.  The  file  must  be  in 
the  current  drive  and  directory  or  in  a  drive  and/or  directory  specified  in  the  command 
path. 
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The  optional  parameters  parameter  represents  any  parameters  that  may  be  required  by 
batch-file. 

Example:  Suppose  the  batch  file  SORTFILE.BAT  accepts  one  parameter.  The  following 
command  calls  SORTFILE.BAT,  specifying  NAMES.TXT  as  the  parameter: 

CALL  SORTFILE  NAMES.TXT 

If  NAMES.TXT  was  specified  as  a  command-line  parameter  to  the  calling  batch  file,  the 
CALL  command  could  be 

CALL  SORTFILE  %1 

Commands  from  PC>DOS 

Two  commands  have  been  added  to  MS-DOS  from  earlier  versions  of  PC-DOS:  COMP, 
present  in  PC-DOS  version  1.0,  and  SELECT,  present  in  PC-DOS  version  2.0. 

COMP 

The  COMP  command  compares  two  files  or  sets  of  files  and  reports  any  differences 
encountered.  FC,  a  similar  file-comparison  command  present  in  MS-DOS  versions  2.0  and 
later,  is  still  included  with  MS-DOS  3.3.  See  USER  COMMANDS:  comp;  fc. 

Syntax  for  the  COMP  command  is 

COMP  [driveMfilenamel]  \drive'\\filename2\ 

The  optional  drive  parameter  is  the  drive  letter,  followed  by  a  colon,  of  the  drive  contain¬ 
ing  the  file  to  be  compared.  The  filenamel  parameter  is  the  name  and  location  of  the  file 
to  compare  to  filename2,  filename2  is  the  name  and  location  of  the  file  to  be  compared 
against.  Both  filenames  can  be  preceded  by  a  path;  wildcard  characters  are  permitted  in 
either  filename. 

Example:  The  following  command  tells  MS-DOS  to  compare  the  file  NEWFILE.TXT  in  the 
current  drive  and  directory  to  the  file  OLDFILE.TXT  in  the  \  ARCHIVE  directory  on  drive 
D  and  report  any  differences  encountered: 

C>C0MP  NEWFILE.TXT  D:\ARCHIVE\OLDFILE.TXT  <Enter> 

SELECT 

The  SELECT  command  creates  a  system  disk  with  the  time  format,  date  format,  and  key¬ 
board  layout  configured  for  a  selected  country.  The  syntax  for  SELECT  is 

SELECT  [[drivel']  [drive2'][path]]  [country\[keyboard] 

The  optional  drivel  parameter  is  the  drive  containing  a  disk  with  the  MS-DOS  operating- 
system  files,  the  FORMAT  program,  and  the  country  configuration  files.  The  drive2 
parameter  is  the  drive  containing  the  disk  to  be  formatted  with  the  country-specific  infor¬ 
mation;  this  drive  specifier  can  be  followed  by  a  path.  The  country  parameter  is  a  code 
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that  selects  the  date  and  time  format;  the  information  is  taken  from  the  COUNTRY.SYS 
system  file.  The  keyboard  parameter  is  a  code  that  selects  the  desired  keyboard  layout. 

See  KEYB  below. 

The  SELECT  command 

•  Formats  the  target  disk. 

•  Creates  CONFIG.SYS  and  AUTOEXEC.BAT  files  on  the  target  disk. 

•  Copies  the  contents  of  the  source  disk  to  the  destination  disk. 

Example:  The  following  command,  which  assumes  drive  A  contains  a  valid  system  disk 
and  drive  B  contains  the  disk  to  be  formatted,  creates  a  bootable  system  disk  that  includes 
country-specific  information  and  keyboard  layout  for  Germany: 

OSELECT  A:  B;  049  GR  <Enter> 

Enhanced  commands 

Several  existing  MS-DOS  user  commands  have  been  given  expanded  capabilities  in 
version  3.3.  These  are  presented  alphabetically  in  the  next  few  pages.  See  USER  COM¬ 
MANDS:  APPEND;  ATTRIB;  BACKUP;  FDISK;  MODE. 

APPEND 

The  APPEND  command  specifies  a  search  path  for  data  files — files  whose  extensions  are 
neither  .COM,  .EXE,  nor  .BAT — similar  to  the  command  path  specified  by  the  PATH  com¬ 
mand,  which  searches  only  for  executable  files  with  those  extensions.  APPEND  has  three 
forms,  depending  on  whether  it  is  being  entered  for  the  first  time.  When  it  is  entered  the 
first  time,  the  APPEND  command  now  has  two  optional  switches: 

APPEND  l/E]  [/XI 

The  /E  switch  makes  the  data  path  part  of  the  environment,  like  the  command  path.  The 
data  path  can  then  be  displayed  or  changed  with  both  the  SET  and  APPEND  commands 
and  is  inherited  by  child  processes.  (However,  any  changes  made  to  the  data  path  by  the 
child  process  are  lost  when  the  child  returns  to  its  parent  process.) 

The  /X  switch  causes  calls  to  the  Find  First  File  functions  (Interrupt  21H  Functions  IIH  and 
4EH)  and  the  EXEC  function  (Interrupt  21H  Function  4BH)  to  search  the  data  path.  If /X  is 
not  specified,  only  Interrupt  21H  Function  OFH  (Open  File  with  FCB),  Interrupt  21H  Func¬ 
tion  23H  (Get  File  Size),  and  Interrupt  21H  Function  3DH  (Open  File  with  Handle)  system 
calls  search  the  data  path. 

If  either  /X  or  /E  is  specified  the  first  time  APPEND  is  entered,  a  pathname  cannot  be 
included. 

Subsequent  uses  of  the  command  must  take  the  form 
APPEND  [[drive-^path]  [\[drive']path  . . .] 
or 

APPEND ; 
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The  path  parameter  is  the  name  of  a  directory  that  is  to  be  made  part  of  the  data  path.  The 
user  can  specify  as  many  directory  names  as  will  fit  in  the  128  characters  of  the  command 
line.  Entries  must  be  separated  by  semicolons.  If  APPEND  is  followed  only  by  a  semicolon, 
any  previous  APPEND  paths  are  deleted. 

Example:  The  following  two  APPEND  commands  make  the  data  path  part  of  the  environ¬ 
ment  and  put  the  directories  C:\WORD\PROPOSAL,  C:\WORD\REPORTS,  and 
C:\123\BUDGET  in  the  data  path: 

OAPPEND  /E  <Enter> 

OAPPEND  C : \WORD\PROPOSAL; C : \WORD\REPORTS; C : \1  23\BUDGET  <Enter> 

Because  the  data  path  usually  involves  frequently  used  directories,  the  APPEND  command 
ordinarily  is  placed  in  the  AUTOEXEC.BAT  file. 

Note:  APPEND  is  a  new  command  in  PC-DOS  version  3.3. 

ATTRIB 

The  /S  switch  has  been  added  to  the  ATTRIB  command  so  that  any  attribute  changes  can 
be  applied  to  all  files  in  subdirectories  contained  in  the  specified  directory. 

Example:  The  following  command  sets  the  read-only  attribute  of  all  files  in  the  directory 
C:  \  DOS  and  in  all  its  subdirectories: 

C>ATTRIB  +R  C:/DOS  /S  <Enter> 

BACKUP 

A  formatting  parameter  has  been  added  to  the  BACKUP  command  in  MS-DOS  version  3.3. 
The  /F  switch  tells  MS-DOS  to  format  the  backup  diskette  if  it  hasn’t  been  formatted.  The 
/F  switch  formats  the  backup  diskette  to  the  maximum  capacity  of  the  backup  drive,  so  a 
disk  of  lower  capacity,  such  as  a  360  KB  diskette  in  a  1.2M  drive,  should  not  be  used.  If  this 
switch  is  used,  FORMAT.COM  must  be  available  in  the  current  drive  and  directory  or  in 
one  of  the  directories  named  in  the  environment’s  PATH  string. 

Performance  of  the  BACKUP  command  has  also  been  improved.  Instead  of  storing  each 
file  separately  on  the  backup  disk,  BACKUP  stores  only  two  files:  BACKUP,  www,  which 
contains  all  the  backed-up  files,  and  CONTROL,  nnn,  which  contains  the  pathnames  of  the 
backed-up  files. 

FDISK 


FDISK  can  now  create  a  new  type  of  MS-DOS  partition  called  an  extended  partition  on  a 
fixed  disk.  An  extended  partition  can  contain  multiple  logical  drives  and  allows  the  use  of 
very  large  fixed  disks.  Each  logical  drive  is  still  limited  to  32  MB. 

An  extended  partition  is  not  bootable.  In  order  for  the  fixed  disk  to  be  bootable,  it  must 
also  contain  a  primary  MS-DOS  partition  that  has  been  formatted  using  the  FORMAT  com¬ 
mand  with  the  /S  switch  so  that  it  contains  a  system  boot  record  and  the  operating-system 
files. 
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MODE 

The  MODE  command  now  supports  two  additional  serial  ports  (COM3  and  COM4)  and 
increases  the  maximum  serial  transmission  rate  to  19,200  baud. 

Some  additional  options  have  been  added  to  MODE  to  support  code-page  switching.  See 
MODE  Command  Changes  below. 

New  national  language  support 

The  new  national  language  support  in  MS-DOS  version  3.3  replaces  the  methods  used  in 
previous  versions  to  change  the  keyboard  layout  and  the  display  and  printer  character  sets 
so  that  more  than  one  language  could  be  used.  These  changes  are  extensive:  four  new  or 
modified  system  files,  three  new  commands,  four  new  options  for  the  MODE  command,  a 
new  parameter  for  the  GRAFTABL  command,  and  a  new  parameter  for  the  COUNTRY  and 
DEVICE  configuration  commands. 

Code  pages  and  code-page  switching 

The  key  element  of  the  new  national  language  support  is  the  code  page,  a  table  of  256 
character  correspondence  codes.  MS-DOS  recognizes  both  a  hardware  code  page,  which  is 
the  character  correspondence  table  built  into  a  device,  and  a  prepared  code  page,  which  is 
an  alternate  character  correspondence  table  available  through  MS-DOS.  The  current  code 
page  is  the  code  page  most  recently  selected. 

The  hardware  code  page  for  a  device  is  determined  by  the  country  for  which  the  device 
was  manufactured.  The  user  selects  a  prepared  code  page,  from  a  list  of  five  included  with 
MS-DOS  version  3-3,  by  using  the  new  CP  PREPARE  option  of  the  MODE  command.  See 
MODE  Command  Changes  below. 

The  new  national  language  support  is  often  referred  to  as  code-page  switching  because, 
after  the  devices  and  code  pages  required  by  the  system  have  been  defined,  the  only  com¬ 
mands  the  user  must  deal  with  simply  switch  from  one  code  page  to  another.  In  order  to 
use  the  new  national  language  support,  device  drivers  must  support  code-page  switching 
and  the  devices  must  be  able  to  display  the  full  character  sets. 

Code  pages  are  numbered.  The  identifying  numbers  have  no  relationship  to  the  country 
code  introduced  with  previous  versions  of  MS-DOS  and  used  by  the  COUNTRY  configura¬ 
tion  command.  Five  code  pages  are  included  with  version  3.3: 


Page  Number  Configuration 


437 

United  States 

850 

Multilingual 

860 

Portugal 

863 

Canadian  French 

865 

Norway/Denmark 
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Code  page  437  is  the  character  correspondence  table  used  in  previous  versions  of 
MS-DOS.  Its  character  set  supports  United  States  English  and  includes  many  accented 
characters  used  in  other  languages.  It  is  the  hardware  code  page  for  most  countries. 

Code  page  850  replaces  two  of  the  four  box-drawing  sets  and  some  of  the  mathematical 
symbols  in  code  page  437  with  additional  accented  characters.  It  supports  English  and 
most  Latin-based  European  languages. 

Code  page  860  is  for  Portuguese,  code  page  863  is  for  Canadian  French,  and  code  page  865 
is  for  Norwegian/Danish.  These  pages  are  the  hardware  code  pages  for  the  specified 
countries. 

Setting  up  the  system  for  code-page  switching 

Although  several  commands  are  required  to  manage  national  language  support,  the 
process  is  fairly  straightforward.  Setting  up  the  system  requires  the  following: 

•  A  DEVICE  configuration  command  in  CONFIG.SYS  to  load  a  driver  for  each  device 
that  supports  code-page  switching. 

•  An  NLSFUNC  command  in  AUTOEXEC.BAT  to  load  the  memory-resident  national 
language  support  functions. 

•  A  MODE  CP  PREPARE  command  in  AUTOEXEC.BAT  to  prepare  code  pages  for  each 
device  that  supports  code-page  switching. 

•  A  CHCP  command  in  AUTOEXEC.BAT  to  select  the  initial  code  page. 

•  Optionally,  a  KEYB  command  in  AUTOEXEC.BAT  to  select  the  initial  keyboard 
layout. 

After  starting  the  system  with  these  commands  in  CONFIG.SYS  and  AUTOEXEC.BAT,  only 
a  MODE  CP  SELECT  command  is  required  to  change  to  a  different  language  during  an 
MS-DOS  session. 

The  COUNTRY  configuration  command  is  still  used  to  control  country-specific  charac¬ 
teristics  such  as  the  time  and  date  format  and  currency  symbol.  An  added  parameter  in  the 
COUNTRY  command  lets  the  user  also  specify  a  code  page.  See  Modified  National  Lan¬ 
guage  Support  Commands  below. 

The  system  files 

MS-DOS  version  3.3  includes  four  system  files  that  support  the  national  language  functions: 
two  device  drivers  and  two  system  information  files. 

The  device  drivers  are  PRINTER.SYS  and  DISPLAY.SYS.  These  drivers  implement  code- 
page  switching  for  the  IBM  Proprinter  Model  4201  and  Quietwriter  III  Model  5202  printers 
and  for  the  EGA,  PC  Convertible  LCD,  and  PS/2  display  adapters.  They  also  support  all 
display  adapters  compatible  with  the  EGA. 

The  information  files  are  COUNTRY.SYS,  which  contains  information  such  as  time  and 
date  formats  and  currency  symbols,  and  KEYBOARD.SYS,  which  contains  the  scan-code- 
to-ASCII  translation  tables  for  the  various  keyboard  layouts. 
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The  new  support  commands 

The  new  national  language  support  in  MS-DOS  version  3.3  adds  three  MS-DOS  com¬ 
mands:  Change  Code  Page  (CHCP),  Keyboard  (KEYB),  and  National  Language  Support 
Functions  (NLSFUNC). 

CHCP 

The  Change  Code  Page  (CHCP)  command  tells  MS-DOS  which  code  page  to  use  for  all 
devices  that  support  code-page  switching. 

The  NLSFUNC  command  must  be  executed  before  the  CHCP  command  can  be  used. 

CHCP  is  a  system-wide  command:  It  specifies  the  code  page  used  by  MS-DOS  and  each 
device  attached  to  the  system  that  supports  code-page  switching.  The  CP  SELECT  option 
of  the  MODE  command,  on  the  other  hand,  specifies  the  code  page  for  a  single  device. 

If  the  code  page  specified  with  CHCP  is  not  compatible  with  a  device,  CHCP  responds 

Code  page  nnn  not  prepared  for  all  devices 

If  the  code  page  specified  with  CHCP  was  not  first  identified  with  the  CP  PREPARE  option 
of  the  MODE  command,  CHCP  responds 

Code  page  nnn  not  prepared  for  system 

The  CHCP  command  has  one  optional  parameter: 

CHCP  [code-page] 

The  code-page  parameter  is  the  three-digit  number  that  specifies  the  code  page  MS-DOS 
is  to  use.  If  code-page  is  omitted,  CHCP  displays  the  current  MS-DOS  code  page. 

Examples:  The  following  command  changes  the  system  code  page  to  850: 

OCHCP  850  <Enter> 

If  the  current  code  page  is  850  and  CHCP  is  entered  without  parameters,  MS-DOS 
responds: 

Active  code  page:  850 

KEYB 

The  Keyboard  (KEYB)  command  selects  a  keyboard  layout  by  changing  the  scan-code-to- 
ASCII  translation  table  used  by  the  keyboard  driver.  It  replaces  the  KEYBxx  commands 
used  in  earlier  versions  of  MS-DOS  to  select  keyboard  layouts. 

The  first  time  KEYB  is  executed,  it  loads  the  memory-resident  keyboard  driver  and  the 
translation  table,  thereby  increasing  the  size  of  MS-DOS  by  slightly  more  than  7  KB.  Subse¬ 
quent  executions  simply  load  a  different  translation  table,  which  replaces  the  previously 
loaded  translation  table  and  accommodates  a  different  country-specific  keyboard  layout. 

The  KEYB  command  has  three  optional  parameters: 

KEYB  [countryi, [code-page], kbdfile]] 
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The  country  parameter  is  one  of  the  following  two-character  country  codes: 


Country 

Code 

Country 

Code 

Australia 

US 

Netherlands 

NL 

Belgium 

BE 

Norway 

NO 

Canada 

Portugal 

PO 

English 

us 

Spain 

SP 

French 

CF 

Sweden 

sv 

Denmark 

DK 

Switzerland 

Finland 

SU 

French 

SF 

France 

FR 

German 

SG 

Germany 

GR 

United  Kingdom 

UK 

Italy 

IT 

United  States 

US 

Latin  America 

LA 

The  code-page  parameter  is  the  three-digit  number  that  specifies  the  code  page  defining 
the  character  set  that  MS-DOS  is  to  use. 

If  the  specified  country  code  and  code  page  aren’t  compatible,  KEYB  responds: 

Code  page  requested  nnn  is  not  valid  for  given  keyboard  code 

If  KEYB  is  entered  with  no  parameters,  MS-DOS  displays  the  currently  active  keyboard 
country  code,  keyboard  code  page,  and  console  device  code  page. 

Examples:  The  following  command  selects  the  French  keyboard  layout,  code  page  850, 
and  the  keyboard  definition  file  named  C:\DOS\KEYBOARD.SYS: 

OKEYB  FR,  8  50,  C:\D0S\KEYB0ARD.  SYS  <Enter> 

If  the  code  page  is  omitted  but  the  keyboard  definition  file  is  specified,  the  comma  must 
be  included  to  show  the  missing  parameter: 

OKEYB  FR, ,  C:\D0S\KEYB0ARD.  SYS  <Enter> 

NLSFUNC 

The  National  Language  Support  Function  (NLSFUNC)  command  loads  a  memory-resident 
program  that  implements  code-page  switching.  It  also  allows  the  user  to  name  the  file  that 
contains  country-specific  information — such  as  date  format,  time  format,  and  currency 
symbol —  if  there  is  no  COUNTRY  configuration  command  in  CONFIG.SYS.  NLSFUNC 
must  be  used  before  the  Change  Code  Page  (CHCP)  command. 

If  national  language  support  is  needed  for  every  session,  NLSFUNC  should  be  placed  in  the 
AUTOEXEC.BAT  file. 

The  NLSFUNC  command  has  one  optional  parameter: 

NLSFUNC  [country-file] 
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The  country-file  parameter  is  the  name  of  the  country  information  file  (in  most  imple¬ 
mentations  of  MS-DOS,  COUNTRY.SYS).  If  country  file  is  omitted,  MS-DOS  defaults  to  the 
name  of  the  country  information  file  specified  in  the  COUNTRY  configuration  command 
in  CONFIG.SYS;  if  there  is  no  COUNTRY  configuration  command  in  CONFIG.SYS, 
MS-DOS  looks  for  a  file  named  COUNTRY.SYS  in  the  root  directory  of  the  current  drive. 

Example:  The  following  command  loads  the  NLSFUNC  program  and  specifies 
C:\DOS\COUNTRY.SYS  as  the  country  information  file: 

ONLSFUNC  C:\DOS\COUNTRY.SYS  <Enter> 

The  modified  support  commands 

The  new  national  language  support  changes  two  configuration  commands — COUNTRY 
and  DEVICE — and  two  general  MS-DOS  commands — GRAFTABL  and  MODE. 

COUNTRY 

The  COUNTRY  configuration  command  now  has  three  parameters: 
CO\JKYK{=country-codeXcode-page]Xcountryfile] 

The  country-code  parameter  is  one  of  the  following  three-digit  country  codes  (identical  to 
the  specified  country’s  international  telephone  prefix): 


Country  Code  Country  Code 


Arabia 

785 

Australia 

061 

Belgium 

Canada 

032 

English 

001 

French 

002 

Denmark 

045 

Finland 

358 

France 

033 

Germany 

049 

Israel 

972 

Italy 

039 

Latin  America 

003 

Netherlands 

031 

Norway 

047 

Portugal 

351 

Spain 

034 

Sweden 

046 

Switzerland 

French 

041 

German 

041 

United  Kingdom 

044 

United  States 

001 

The  code-page  parameter  is  the  three-digit  number  that  specifies  the  code  page  defining 
the  character  set  that  MS-DOS  is  to  use. 

The  country-file  parameter  is  the  name  of  the  file  that  contains  the  country-specific 
information;  the  name  of  the  file  can  be  preceded  by  a  drive  and/or  path.  If  country-file  is 
omitted,  MS-DOS  defaults  to  the  file  COUNTRY.SYS,  which  it  looks  for  in  the  root  direc¬ 
tory  of  the  current  drive. 
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The  COUNTRY  command  is  not  required;  if  it  is  not  included  in  CONFIG.SYS,  MS-DOS 
defaults  to  country  001  (US),  code  page  437,  and  country  information  file  COUNTRYSYS  in 
the  root  directory  of  the  current  drive. 

Example:  The  following  CONFIG.SYS  command  specifies  the  French  country  code,  code 
page  850,  and  C:\DOS\COUNTRY.SYS  as  the  country  information  file: 

COUNTRY=033, 850, C : \DOS\COUNTRY . SYS 

DEVICE 

Two  options  have  been  added  to  the  DEVICE  configuration  command  that  allow  the  user 
to  specify  the  display  and  printer  drivers  that  support  code-page  switching. 

The  display  driver  that  supports  code-page  switching  is  DISPLAY.SYS.  It  supports  the  IBM 
Enhanced  Graphics  Adapter  (EGA),  the  IBM  Personal  System/2  display  adapter,  and  all  dis¬ 
play  adapters  compatible  with  either  of  these.  The  Monochrome  Display  Adapter  (MDA) 
and  the  Color/Graphics  Adapter  (CGA)  do  not  support  code-page  switching. 

If  the  ANSI.SYS  display  driver  is  also  used,  the  DEVICE  command  that  defines  it  must  pre¬ 
cede  the  DEVICE  command  that  defines  DISPLAY.SYS. 

When  used  to  specify  the  display  driver,  the  DEVICE  command  has  five  parameters: 
XyESfKE^driver  CON=(/j;p^[,[/?t/;cp][,pri^pcp[,swfc-:^w^s]]]) 

The  driver  parameter  is  the  name  of  the  file  that  contains  the  display  driver;  the  filename 
can  be  preceded  by  a  drive  and/or  path.  If  driver  is  omitted,  MS-DOS  defaults  to  the  file 
DISPLAY.SYS,  which  it  looks  for  in  the  root  directory  of  the  current  drive. 

The  type  parameter  defines  the  type  of  display  adapter  attached  to  the  system.  It  must  be 
one  of  the  following: 


Code  Adapter 

MONO  Monochrome  display/printer  adapter 

CGA  Color/graphics  adapter 

EGA  Enhanced  graphics  adapter  or  IBM  Personal  System/2  display  adapter 

LCD  IBM  PC  Convertible  liquid  crystal  display 

The  hwcp  parameter  is  the  three-digit  number  that  specifies  the  hardware  code  page 
supported  by  the  display  adapter: 


Code  Configuration 

437  United  States  (default) 

850  Multilingual 

860  Portugal 

863  Canadian  French 

865  Norway/Denmark 
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The  prepcp  parameter  is  the  number  of  additional  code  pages  the  display  can  support. 
These  are  referred  to  as  prepared  code  pages  and  must  be  defined  by  the  CP  PREPARE 
option  of  the  MODE  command.  If  type  is  either  MONO  or  CGA,  prepcp  must  be  0;  the 
default  is  0.  If  type  is  either  EGA  or  LCD,  prepcp  can  be  any  value  from  1  through  12;  the 
default  is  1.  If  hwcp  is  437,  prepcp  should  be  allowed  to  default  to  1;  if  hwcp  is  not  437, 
prepcp  should  be  set  to  2. 

The  sub-fonts  parameter  is  the  number  of  subfonts  supported  for  each  code  page.  If  type 
is  either  MONO  or  CGA,  sub-fonts  must  be  0;  the  default  is  0.  If  type  is  EGA,  sub-fonts  can 
be  1  or  2;  the  default  is  2.  If  type  is  LCD,  sub-fonts  can  be  1  or  2;  the  default  is  1. 

Example:  The  following  CONFIG.SYS  command  specifies  C:\DOS\DISPLAY.SYS  as  the 
display  driver  for  an  EGA  whose  hardware  code  page  is  437.  The  parameter  for  prepared 
code  pages  is  allowed  to  default  to  1  and  the  parameter  for  subfonts  is  allowed  to  default 
to  2. 

DEVICE=C: \DOS\DISPLAY.SYS  C0N= (EGA, 437) 

The  printer  driver  that  supports  code-page  switching  is  PRINTER.SYS.  It  supports  the  IBM 
Proprinter  Model  4201,  the  IBM  Quietwriter  III  Printer  Model  5202,  and  all  printers  com¬ 
patible  with  either  of  these. 

When  used  to  specify  the  printer  driver,  the  DEVICE  configuration  command  has  five 
parameters: 

YyEVlCE^  driver  port=^itype[Xhwcpi[, prepcp]]) 

The  driver  parameter  is  the  name  of  the  file  that  contains  the  printer  driver;  the  filename 
can  be  preceded  by  a  drive  and/or  path.  If  driver  is  omitted,  MS-DOS  defaults  to  the  file 
PRINTER.SYS,  which  it  looks  for  in  the  root  directory  of  the  current  drive. 

The  port  parameter  is  the  MS-DOS  device  name  of  the  printer  port  being  defined:  LPTl 
(or  PRN),  LPT2,  or  LPT3.  A  different  set  of  type,  hwcp,  and  prepcp  parameters  can  be  spec¬ 
ified  for  each  of  the  three  printer  ports. 

The  type  parameter  defines  the  type  of  printer  attached  to  the  printer  port.  It  must  be  one 
of  the  following: 


Code  Printer 

4201  IBM  Proprinter  Model  4201 

5202  IBM  Quietwriter  III  Printer  Model  5202 

The  hwcp  parameter  is  a  three-digit  number  that  specifies  the  hardware  code  page  sup¬ 
ported  by  the  hardware: 
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Code  Configuration 

437  United  States  (default) 

850  Multilingual 

860  Portugal 

863  Canadian  French 

865  Norway/Denmark 

If  type  is  5202,  two  hardware  code-page  numbers  can  be  specified,  enclosed  in  paren¬ 
theses  and  separated  by  a  comma.  If  two  hardware  code  pages  are  specified,  prepcp  must 
be  0. 

The  prepcp  parameter  is  the  number  of  additional  code  pages  (referred  to  as  prepared 
code  pages)  for  which  MS-DOS  must  reserve  buffer  space;  its  value  can  be  from  0  through 
12.  These  additional  code  pages  must  be  defined  by  the  CP  PREPARE  option  of  the  MODE 
command.  If  hwcp  is  437,  prepcp  should  be  set  to  1;  if  hwcp  is  not  437  and  only  one  hwcp 
value  is  specified,  prepcp  should  be  set  to  2. 

Examples:  The  following  CONFIG.SYS  command  defines  C:\DOS\PRINTER.SYS  as  the 
printer  driver  for  the  PRN  device.  The  printer  is  an  IBM  Proprinter  Model  4201  whose  hard¬ 
ware  code  page  is  437,  and  MS-DOS  is  instructed  to  allow  for  one  prepared  code  page: 

DEVICE=C:\DOS\PRINTER.SYS  PRN= (4201 , 437, 1 ) 

The  next  CONFIG.SYS  command  defines  C:\DOS\PRINTER.SYS  as  the  printer  driver  for 
ports  LPTl  and  LPT2.  The  printer  attached  to  LPTl  is  the  same  as  in  the  previous  com¬ 
mand;  the  printer  attached  to  LPT2  is  an  IBM  Quietwriter  III  Printer  Model  5202  with  two 
hardware  code  pages  (437  and  850).  For  the  second  printer,  MS-DOS  is  instructed  to  allow 
for  no  prepared  code  pages. 

DEVICE=C:\DOS\PRINTER.SYS  LPT 1 = (4201 , 437 , 1)  LPT2=(5202, (437,850) ,0) 

GRAFTABL 

The  GRAFTABL  command  now  has  two  forms: 

GRAFTABL  [code-page] 
or 

GRAFTABL  /STATUS 

The  first  form  of  the  command  loads  a  code  page  for  the  color/graphics  adapter  (CGA)  so 
that  its  character  set  matches  that  used  by  MS-DOS  and  other  devices  when  displaying  the 
upper  128  characters.  The  code-page  parameter  is  the  three-digit  number  that  specifies  the 
code  page  defining  the  character  set  that  GRAFTABL  is  to  use. 

The  /STATUS  switch  causes  GRAFTABL  to  display  the  name  of  the  graphics  character  set 
table  currently  in  use. 
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MODE 

National  language  support  adds  four  options  to  the  MODE  command: 


Option 


Action 


CODEPAGE 
CODEPAGE  PREPARE 
CODEPAGE  REFRESH 

CODEPAGE  SELECT 


Displays  the  code  pages  available  and  active. 

Defines  the  code  pages  selected  for  use. 

Restores  code-page  contents  damaged  by  hardware  error  or 
other  causes. 

Selects  a  code  page  for  a  particular  device. 


(CODEPAGE  can  be  abbreviated  to  CP  in  the  command  line.) 

When  used  to  display  the  status  of  the  code  pages,  the  MODE  command  has  one 
parameter: 

MODE  device  CP 

The  device  parameter  is  the  name  of  the  device  whose  code-page  status  is  to  be  dis¬ 
played.  It  can  be  CON,  PRN,  LPTl,  LPT2,  or  LPT3. 

Example:  The  following  command  displays  the  status  of  the  console  device: 

OMODE  CON  CP  <Enter> 

When  used  to  define  the  code  page  or  pages  to  be  used  with  a  device,  the  MODE  com¬ 
mand  has  three  parameters: 

MODE  device  CP  ¥RE?AEE^icode-page font-fil^ 

The  device  parameter  is  the  name  of  the  device  for  which  the  code  page  or  pages  are  to  be 
prepared.  It  can  be  CON,  PRN,  LPTl,  LPT2,  or  LPT3. 

The  code-page  parameter  is  one  or  more  of  the  three-digit  numbers,  enclosed  in  parenthe¬ 
ses,  that  specify  the  code  page  to  be  used  with  device.  If  more  than  one  code-page  number 
is  specified,  the  numbers  must  be  separated  with  spaces. 

The  font-file  parameter  is  the  name  of  the  code-page  file  that  contains  the  font  informa¬ 
tion  for  device.  The  files  provided  for  IBM  devices  include 


File  Device 

EGA.CPI  IBM  Enhanced  Graphics  Adapter  (EGA)  and  EGA-compatible  display 

adapters 

4201 .CPI  IBM  Proprinter  Model  4201 

5202.CPI  IBM  Quietwriter  III  Printer  Model  5202 

LCD.CPI  IBM  Convertible  liquid  crystal  display 
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Example:  Assume  the  display  is  attached  to  an  EGA.  The  following  command  prepares 
code  pages  437  and  850  for  the  console,  specifying  C:\DOS\EGA.CPI  as  the  code-page 
information  file: 

OMODE  CON  CP  PREPARE=  (  (437  850)  C:\DOS\EGA.CPI)  <Enter> 

When  used  to  select  a  code  page  for  a  device,  the  MODE  command  has  two  parameters: 
MODE  device  CP  SE1ECY=  code-page 

The  device  parameter  is  the  name  of  the  device  for  which  the  code  page  is  to  be  selected. 
Permissible  values  are  CON,  PRN,  LPTl,  LPT2,  and  LPT3. 

The  code-page  parameter  is  the  three-digit  number  that  specifies  the  code  page  to  be  used 
with  device. 

Example:  The  following  command  selects  code  page  850  for  the  console: 

OMODE  CON  CP  SELECT=850  <Enter> 

Setting  up  code-page  switching  for  an  EGA-only  system 

Figure  A-1  shows  the  commands  required  to  implement  the  new  national  language  support 
for  a  system  that  includes  only  a  display  attached  to  an  EGA  or  EGA-compatible  adapter. 
The  hardware  code  page  of  the  EGA  is  437  (United  States  English)  and  the  system  is  set  up 
to  handle  code  pages  437  and  850.  All  MS-DOS  files  are  assumed  to  be  in  the  directory 
\DOS  on  the  disk  in  drive  C.  If  the  ANSI.SYS  driver  is  not  used,  the  configuration  com¬ 
mand  DEVICE=C:\DOS\ANSI.SYS  should  be  omitted  from  CONFIG.SYS;  if  ANSI.SYS  is 
used,  however,  the  DEVICE  configuration  command  that  defines  it  must  precede  the 
DEVICE  configuration  command  that  defines  DISPLAY.  SYS. 

Commands  in  CONFIG.SYS: 

COUNTRY=001 , 4 37, C:\DOS\COUNTRY. SYS 
DEVICE=C : \D0S\ANSI . SYS 
DEVICE=C:\DI SPLAY. SYS  CON= (EGA, 437, 1 ) 

Commands  in  AUTOEXEC.BAT: 

NLSFUNC  C:\DOS\COUNTRY.SYS 

MODE  CON  CP  PREPARE=( (437  850)  C:\DOS\EGA.CPI) 

MODE  CON  CP  SELECT=437 

KEYB  US, 437, C:\DOS\KEYBOARD. SYS 

Figure  A-1.  Setup  commands  for  a  system  with  an  EGA  only. 

When  the  system  is  started,  code  page  437  is  selected  for  MS-DOS,  the  display,  and  the 
keyboard.  To  change  to  code  page  850  during  the  session,  simply  type 

OCHCP  850  <Enter> 
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Setting  up  code-page  switching  for  a  PS/2  and  printer 

Figure  A-2  shows  the  commands  required  to  implement  the  new  national  language  sup¬ 
port  for  an  IBM  Personal  System/2  or  compatible  system  that  includes  both  a  PS/2,  EGA,  or 
EGA-compatible  display  adapter  and  an  IBM  Proprinter  Model  4201.  The  hardware  code 
page  of  both  devices  is  437  (United  States  English)  and  the  system  is  set  up  to  handle  code 
pages  437  and  850. 

Conunands  in  CONFIG.SYS: 

COUNTRY=0  0 1 , 4  3  7 , C : \D0S \C0UNTRY . SYS 

DEVICE=C : \DOS\ANSI . SYS 

DEVICE=C : \DISPLAY . SYS  C0N= (EGA, 437,1) 

DEVICE=C:\DOS\PRINTER.SYS  PRN= (4201 , 437, 1 ) 

Commands  in  AUTOEXEC.BAT: 

NLSFUNC  C:\DOS\COUNTRY.SYS 

MODE  CON  CP  PREPARE=( (437  850)  C:\DOS\EGA.CPI) 

MODE  PRN  CP  PREPARE=( (437  850)  C:\DOS\4202.CPI) 

MODE  CON  CP  SELECT=850 
MODE  PRN  CP  SELECT=850 
KEYS  US, 8 50, C:\DOS\KEYBOARD. SYS 

Figure  A~2.  Setup  commands for  a  PS/2  with  display  and  printer. 

Again,  all  MS-DOS  files  are  assumed  to  be  in  the  directory  \DOS  on  the  disk  in  drive  C.  If 
the  ANSI.SYS  driver  is  not  used,  the  configuration  command  DEVICE=C:\DOS\ANSI.SYS 
should  be  omitted  from  CONFIG.SYS;  if  ANSI.SYS  is  used,  however,  the  DEVICE  configur¬ 
ation  command  that  defines  it  must  precede  the  DEVICE  configuration  command  that 
defines  DISPLAY.SYS. 


Version  3-3  Programming  Considerations 

The  changes  introduced  in  MS-DOS  version  3.3  that  are  of  primary  interest  to  the  pro¬ 
grammer  include 

•  New  Interrupt  21H  function  calls  for  file  management  and  internationalization  support 

•  An  extension  to  the  definition  of  the  MS-DOS  lOCTL  function  for  code-page  switch¬ 
ing,  plus  the  addition  of  the  underlying  device-driver  support 

•  Support  for  extended  MS-DOS  partitions  on  fixed  disks 

Each  of  these  areas  is  discussed  in  detail  below. 

New  file-management  functions 

MS-DOS  version  3.3  includes  two  new  Interrupt  21H  file-management  functions:  Set  Han¬ 
dle  Count  (Function  67H)  and  Commit  File  (Function  68H). 
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Set  Handle  Count 

The  Set  Handle  Count  function  (Interrupt  21H  Function  67H)  allows  a  single  process 
to  have  more  than  20  handles  for  files  or  devices  open  simultaneously.  Function  67H  is 
invoked  by  issuing  a  software  Interrupt  21H  with 

AH  =  67H 

BX  =  number  of  desired  handles 
On  return, 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code 

For  each  process,  the  operating  system  maintains  a  table  that  relates  handle  numbers  for 
the  process  to  MS-DOS’s  internal  global  table  for  all  open  files  in  the  system.  In  MS-DOS 
versions  3.0  and  later,  the  per-process  table  is  ordinarily  stored  within  the  reserved  area  of 
the  program  segment  prefix  (PSP)  and  has  only  enough  room  for  20  handle  entries.  If  20  or 
fewer  handles  are  requested  in  register  BX,  Function  67H  takes  no  action  and  returns  a 
success  signal.  If  more  than  20  handles  are  requested,  however.  Function  67H  allocates  on 
behalf  of  the  calling  program  a  new  block  of  memory  that  is  large  enough  to  hold  the 
expanded  table  of  handle  numbers  and  then  copies  the  process’s  old  handle  table  to  the 
new  table.  Because  the  function  will  fail  if  the  system  does  not  have  sufficient  free  memory 
to  allocate  the  new  block,  most  programs  need  to  make  a  call  to  Interrupt  21H  Function 
4AH  (Resize  Memory  Block)  to  “shrink”  their  initial  memory  block  allocations  before  call¬ 
ing  Function  67H. 

Function  67H  does  not  fail  if  the  number  requested  is  larger  than  the  available  entries  in 
the  system’s  global  table  for  file  and  device  handles.  However,  a  subsequent  attempt  to 
open  a  file  or  device  or  to  create  a  new  file  will  fail  if  all  the  entries  in  the  system’s  global 
file  table  are  in  use,  even  if  the  requesting  process  has  not  used  up  all  its  own  handles. 

(The  size  of  the  global  table  is  controlled  by  the  FILES  entry  in  the  CONFIG.SYS  file.  See 
USER  COMMANDS:  CONFIG.SYS:  files;  PROGRAMMING  IN  THE  MS-DOS  ENVIRON¬ 
MENT:  Programming  for  ms-dos:  File  and  Record  Management.) 

Example:  Set  the  maximum  handle  count  for  the  current  process  to  30,  so  that  the  process 
can  have  as  many  as  25  files  or  devices  open  simultaneously  (5  of  the  handles  are  already 
expended  by  the  MS-DOS  standard  devices  when  the  process  starts  up).  Note  that  a 
FILES=30  (or  greater  value)  entry  in  the  CONFIG.SYS  file  also  is  required  for  the  process 
to  successfully  open  30  files  or  devices. 
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mov 

ah, 67h 

;  Function  67H  =  set  handle  count 

mov 

bx,30 

;  Maximum  number  of  handles. 

int 

21h 

;  Transfer  to  MS-DOS. 

jc 

error 

;  Jump  if  function  failed. 

Commit  File 

The  Commit  File  function  (Interrupt  21H  Function  68H)  forces  all  data  in  MS-DOS’s  inter¬ 
nal  buffers  that  is  associated  with  a  given  handle  to  be  written  to  disk  and  forces  the  corre¬ 
sponding  disk  directory  and  file  allocation  table  (FAT)  information  to  be  updated.  By 
calling  this  function  at  appropriate  points  within  its  execution,  a  program  can  ensure  that 
newly  entered  data  will  not  be  lost  if  there  is  a  power  failure,  if  the  program  crashes,  or  if 
the  user  fails  to  terminate  the  program  properly  before  turning  off  the  machine.  Function 
68H  is  called  by  issuing  a  software  Interrupt  21H  with 

AH  =68H 

BX  =  handle  for  previously  opened  file. 

On  return. 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code 

The  effect  of  Function  68H  is  equivalent  to  closing  and  reopening  the  file  or  to  duplicating 
a  file  handle  with  Interrupt  21H  Function  45H  (Duplicate  File  Handle)  and  then  closing  the 
duplicate.  See  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for 
MS-DOS:  File  and  Record  Management.  However,  Function  68H  has  the  advantages  that  the 
application  will  not  lose  control  of  the  file  (as  could  happen  with  the  close-open  sequence 
in  a  networking  environment)  and  that  it  will  not  fail  because  of  a  lack  of  handles  (as  the 
duplicate  handle  method  might). 

Note:  Function  68H  operations  requested  on  a  handle  associated  with  a  character  device 
return  a  success  flag  but  have  no  effect. 

Example:  Assume  that  the  file  MYFILE.DAT  has  been  opened  previously  and  that  the  han¬ 
dle  for  the  file  is  stored  in  the  variable  fhandle.  Call  Function  ^H  to  ensure  that  any  data 
in  MS-DOS’s  internal  buffers  associated  with  the  handle  is  written  out  to  disk  and  that  the 
directory  and  FAT  are  up-to-date. 
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fname 

db 

'MYFILE.DAT' , 0 

;  ASCI I Z  filename. 

fhandle 

dw 

0 

;  Handle  from  Open  operation 

mov 

ah, 68h 

;  Function  68H  =  commit  file 

mov 

bx, fhandle 

;  Handle  from  previous  open. 

int 

21h 

;  Transfer  to  MS-DOS. 

jc 

error 

;  Jump  if  function  failed. 

New  internationalization  support  functions 

MS-DOS  version  3.3  includes  two  new  Interrupt  21H  internationalization  support  func¬ 
tions:  Get  Extended  Country  Information  (Function  65H)  and  Select  Code  Page  (Function 
66H). 

Get  Extended  Country  Information 

The  Get  Extended  Country  Information  function  (Interrupt  21H  Function  65H)  returns  a 
superset  of  the  internationalization  information  obtained  with  Interrupt  21H  Function  38H 
(Get/Set  Current  Country).  Function  65H  is  called  by  issuing  a  software  Interrupt  21H  with 

AH  =  65H 

AL  =  information  ID  code: 

OlH  get  general  internationalization  information 

02H  get  pointer  to  uppercase  table 

04H  get  pointer  to  filename  uppercase  table 
06H  get  pointer  to  collating  sequence  table 
BX  =  code  page  of  interest  (active  CON  device  =  -1) 

CX  =  length  of  buffer  to  receive  information  (error  returned  if  less  than  5) 

DX  =  country  ID  (default  =  -1) 

ES:DI  =  address  of  buffer  to  receive  information 

On  return, 

If  function  is  successful: 

Carry  flag  is  clear. 

Requested  data  is  in  calling  program's  buffer. 

If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code 

Function  65H  may  fail  if  either  the  country  code  or  the  code-page  number  is  invalid  or  if 
the  code  page  does  not  match  the  country  code.  If  the  buffer  to  receive  the  information  is 
at  least  5  bytes  but  is  too  short  for  the  requested  information,  the  data  is  truncated  and  no 
error  is  returned. 
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The  format  of  the  data  returned  by  Subfunction  OlH  in  the  calling  program’s  buffer  is 


Field 

Size 

Information  ID  code  (OlH) 

Byte 

Length  of  following  buffer  (38  or  less) 

Word 

Country  ID 

Word 

Code-page  number 

Word 

Date  format 

Word 

Currency  symbol 

5  bytes 

Thousands  separator 

Word 

Decimal  separator 

Word 

Date  separator 

Word 

Time  separator 

Word 

Currency  format  flags 

Byte 

Digits  in  currency 

Byte 

Time  format 

Byte 

Monocase  routine  entry  point 

Doubleword 

Data  list  separator 

Word 

Reserved 

10  bytes 

See  SYSTEM  CALLS:  Interrupt  21h:  Function 

38H. 

The  format  of  the  data  returned  by  Subfunctions  02H,  04H,  and  06H  is 

Field 

Size 

Information  ID  code  (02H,  04H,  or  06H)  Byte 
Pointer  to  table  Doubleword 


The  uppercase  and  filename  uppercase  tables  are  130  bytes.  The  first  2  bytes  contain  the 
size  of  the  table;  the  subsequent  128  bytes  contain  the  uppercase  equivalents,  if  any,  for 
character  codes  80H  through  OFFH.  The  main  use  of  these  tables  is  to  map  accented  or 
otherwise  modified  vowels  to  their  plain  vowel  equivalents.  Text  translated  using  these 
tables  can  be  sent  to  devices  that  do  not  support  the  IBM  graphics  character  set  or  can  be 
used  to  create  filenames  that  do  not  require  a  special  keyboard  configuration  for  entry. 

The  collating  table  is  258  bytes.  The  first  2  bytes  contain  the  table  length  and  the  next  256 
bytes  contain  the  values  to  be  used  for  the  corresponding  character  codes  (O—OFFH)  dur¬ 
ing  a  sort  operation.  Among  other  things,  this  table  maps  uppercase  and  lowercase  ASCII 
characters  to  the  same  collating  codes  (so  that  sorts  will  be  case  insensitive)  and  maps 
accented  vowels  to  their  plain  vowel  equivalents. 
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Note:  In  some  cases,  a  truncated  translation  table  might  be  presented  to  the  program  by 
MS-DOS.  Applications  should  always  check  the  length  specified  at  the  beginning  of  the 
table  to  be  sure  the  table  contains  a  translation  code  for  the  character  of  interest. 

Example:  Obtain  the  extended  country  information  associated  with  the  default  country 
and  code  page  437. 


buffer 

db 

41  dup  (0) 

Receives  country  information. 

mov 

ax, 6501h 

Function  =  get  extended  info. 

mov 

bx,437 

Code  page . 

mov 

cx,  41 

Length  of  buffer. 

mov 

dx,  -1 

Default  country. 

mov 

di, seg  buffer 

ES:DI  =  buffer  address. 

mov 

es,  di 

mov 

di, offset  buffer 

int 

21h 

Transfer  to  MS-DOS. 

jc 

error 

Jump  if  function  failed. 

In  this  case, 

MS-DOS  fills  the  following  extended  country  information  into  the  buffer: 

buffer 

db 

1 

Information  ID  code 

dw 

38 

Length  of  following  buffer 

dw 

1 

Country  ID  (USA) 

dw 

437 

Code-page  number 

dw 

0 

Date  format 

db 

o 

o 

o 

o 

vy 

Currency  symbol 

db 

’,',0 

Thousands  separator 

db 

*.',0 

Decimal  separator 

db 

'-',0 

Date  separator 

db 

':’,0 

Time  separator 

db 

0 

Currency  format  flags 

db 

2 

Digits  in  currency 

db 

0 

Time  format 

dd 

026ah:176ch 

Monocase  routine  entry  point 

db 

*  '  n 

t  f  U 

Data  list  separator 

db 

10  dup  (0) 

Reserved 

Example:  Obtain  the  pointer  to  the  uppercase  table  associated  with  the  default  country 
and  code  page  437. 


buffer  db  5  dup  (0)  ;  Receives  pointer  information. 


mov  ax, 6502h  ;  Function  =  get  pointer  to 

;  uppercase  table. 


(more) 
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mov 

bx,437 

mov 

cx,  5 

mov 

dx,-1 

mov 

di,seg  buffer 

mov 

es,  di 

mov 

di, offset  buffer 

int 

21h 

jc 

error 

Code  page. 

Length  of  buffer. 
Default  country. 

ES:DI  =  buffer  address. 


Transfer  to  MS-DOS. 

Jump  if  function  failed 


In  this  case,  MS-DOS  fills  the  following  values  into  the  buffer: 

buffer  db  2  ;  Information  ID  code 

dw  0204h  /  Offset  of  uppercase  table 

dw  1 1 40h  ;  Segment  of  uppercase  table 

The  table  at  1140:0204H  contains  the  following  data: 


0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0123456789ABCDEF 

1140:0200 

80 

00 

80 

9A 

45 

41 

8E 

41 

8F 

80 

45 

45 

_ EA.A. .EE 

1140:0210 

45 

49 

49 

49 

8E 

8F 

90 

92 

92 

4F 

99 

4F 

55 

55 

59 

99 

EIII . O.OUUY. 

1140:0220 

9A 

9B 

9C 

9D 

9E 

9F 

41 

49 

4F 

55 

A5 

A5 

A6 

A7 

A8 

A9 

1140:0230 

AA 

AB 

AC 

AD 

AE 

AF 

BO 

B1 

B2 

B3 

B4 

B5 

B6 

B7 

B8 

B9 

1140:0240 

BA 

BB 

BC 

BD 

BE 

BF 

CO 

Cl 

C2 

C3 

C4 

C5 

C6 

C7 

C8 

C9 

1140:0250 

CA 

CB 

CC 

CD 

CE 

CF 

DO 

DI 

D2 

D3 

D4 

D5 

D6 

D7 

D8 

D9 

1140:0260 

DA 

DB 

DC 

DD 

DE 

DF 

EO 

El 

E2 

E3 

E4 

E5 

E6 

E7 

E8 

E9 

1140:0270 

EA 

EB 

EC 

ED 

EE 

EF 

FO 

FI 

F2 

F3 

F4 

F5 

F6 

F7 

F8 

F9 

1140:0280 

FA 

FB 

FC 

FD 

FE 

FF 

Select  Code  Page 

The  Select  Code  Page  function  (Interrupt  21H  Function  66H)  queries  or  selects  the  current 
code  page.  Function  66H  is  called  by  issuing  a  software  Interrupt  21H  with 

AH  =  66H 

AL  =  subfunction: 

OlH  get  code  page 

02H  select  code  page 

BX  =  code  page  to  select  if  AL  =  02H 

On  return, 

If  function  is  successful: 

Carry  flag  is  clear. 

If  AL  was  OlH  on  call: 

BX  =  active  code  page 
DX  =  default  code  page 


1454  The  MS-DOS  Encyclopedia 


Appendix  A:  MS-DOS  Version  3-3 


If  function  is  not  successful: 

Carry  flag  is  set. 

AX  =  error  code 

When  Subfunction  02H  is  used,  MS-DOS  gets  the  new  code  page  from  the  COUNTRY.SYS 
file.  The  device  must  be  previously  prepared  for  code-page  switching  by  including  the 
appropriate  DEVICE  command  in  the  CONFIG.SYS  file  and  by  issuing  the  NLSFUNC  and 
MODE  CP  PREPARE  commands  (usually  by  placing  them  in  the  AUTOEXEC.BAT  file). 

Example:  Force  the  active  code  page  to  be  the  same  as  the  system’s  default  code  page — 
that  is,  return  to  the  code  page  that  was  active  when  the  system  was  first  booted. 


mov 

ax, 6601 h 

;  Function  =  get  code  page. 

int 

21h 

;  Transfer  to  MS-DOS. 

jc 

error 

;  Jump  if  function  failed. 

mov 

bx,  dx 

;  Force  active  page  =  default 

mov 

ax, 6602h 

;  Function  =  set  code  page. 

int 

21h 

;  Transfer  to  MS-DOS. 

jc 

error 

;  Jump  if  function  failed. 

Extension  of  lOCTL 

The  MS-DOS  lOCTL  service  (Interrupt  21H  Function  44H)  and  its  device-driver  under¬ 
pinnings  have  been  extended  to  support  code-page  switching  by  the  interactive  CHCP  and 
MODE  commands  or  by  application  programs.  The  relevant  lOCTL  subfunction  is  OCH 
(Generic  lOCTL  for  Handles).  An  MS-DOS  utility  or  application  program  gains  access  to 
this  subfunction  by  executing  a  software  Interrupt  21H  with 


AH 

=  44H 

AL 

=  0CH 

BX 

=  handle  for  character  device 

CH 

=  category  code: 

OOH 

unknown 

OlH 

COMl,  COM2,  COM3,  or  COM4 

03H 

CON  (keyboard  and  video  display) 

05H 

LPTl,LPT2,orLPT3 

(more) 
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CL  =  function  (minor)  code: 

4AH  select  code  page 

4CH  start  code-page  preparation 

4DH  end  code-page  preparation 

6AH  query  selected  code  page 

6BH  query  prepare  list 

DS:DX  ==  pointer  to  Generic  lOCTL  parameter  block 
On  return, 

If  function  is  successful: 

Carry  flag  is  clear. 

If  function  is  not  successful: 

Carry  flag  is  set. 


AX  =  error  code: 


OlH 

invalid  function  number 

19H 

bad  data  read  from  font  file 

22H 

unknown  command 

26H 

code  page  not  prepared  or  selected 

27H 

code  page  conflict  or  device  or  code  page  not  found  in  file 

29H 

device  error 

31H 

file  contents  not  a  valid  font  or  no  previous  “start  code-page 
preparation”  call 

Additional  information  about  the  cause  of  the  error  can  be  obtained  with  a  call  to  Interrupt 

21H  Function  59H  (Get  Extended  Error  Information). 

The  parameter  blocks  for  minor  codes  4AH,  4DH,  and  6AH  have  the  following  format: 


Field  Size 

Length  of  following  data  Word 

Code  page  ID  Word 

The  parameter  block  for  minor  code  4CH  has  the  following  format: 


Field  Size 


Flags  Word 

Length  of  remainder  of  parameter  Word 

block  (2[w+l]) 

Number  of  code  pages  in  the  Word 

following  list  («) 


(more) 
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Field 

Size 

Code  page  1 

Word 

Code  page  2 

Word 

Code  page  n 

Word 

The  parameter  block  for  minor  code  6BH  has  the  following  format,  assuming  n  hardware 
code  pages  and  m  prepared  code  pages  (w  <=  12,  m  <=  12); 

Field 

Size 

Length  of  following  data  (2[  w+m+2]) 

Word 

Number  of  hardware  code  pages  («) 

Word 

Hardware  code  page  1 

Word 

Hardware  code  page  2 

Word 

Hardware  code  page  n 

Word 

Number  of  prepared  code  pages  (m) 

Word 

Prepared  code  page  1 

Word 

Prepared  code  page  2 

Word 

Prepared  code  page  m 

Woid 

After  a  Start  Code-Page  Preparation  (minor  code  4CH)  call,  the  program  must  write  the 
data  defining  the  code-page  font  to  the  driver  using  one  or  more  lOCTL  Send  Control  Data 
to  Character  Device  (Interrupt  21H  Function  44H  Subfunction  03H)  calls.  The  format  of  the 
data  is  both  device-specific  and  driver-specific.  After  the  font  data  has  been  written  to  the 
driver,  the  program  must  issue  an  End  Code-Page  Preparation  (minor  code  4DH)  call.  If  no 
data  is  written  to  the  driver  between  the  start  and  end  calls,  the  driver  interprets  the  newly 
prepared  code  pages  as  hardware  code  pages. 

A  special  variation  of  Start  Code-Page  Preparation,  called  “refresh,”  is  required  to  actually 
load  the  peripheral  device  with  the  prepared  code  pages.  The  refresh  operation  is  ob¬ 
tained  by  calling  minor  code  4CH  with  each  code-page  position  in  the  parameter  block  set 
to  -1  and  then  immediately  calling  minor  code  4DH. 
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The  device-driver  support  that  corresponds  to  lOCTL  Subfunction  OCH  is  invoked  by  the 
MS-DOS  kernel  via  the  Generic  lOCTL  function  (driver  command  code  19).  The  category 
(major)  and  function  (minor)  codes  described  above,  along  with  a  pointer  to  the  parame¬ 
ter  block,  are  passed  to  the  driver  in  the  request  header.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Customizing  ms-dos:  Installable  Device  Drivers. 

Extended  MS-DOS  partitions 

An  extended  MS-DOS  partition  is  indicated  by  a  system  indicator  byte  value  of  05  in 
the  partition  table  of  the  fixed  disk’s  master  boot  record.  See  PROGRAMMING  IN  THE 
MS-DOS  ENVIRONMENT:  Structure  of  ms-dos:  MS-DOS  Storage  Devices.  An  extended 
partition  is  not  bootable  and  can  be  created  on  a  bootable  fixed-disk  drive  only  if  that 
drive  already  contains  a  primary  MS-DOS  partition  (system  indicator  type  01  or  04).  Fixed 
disks  that  are  not  bootable  can  contain  an  extended  partition  without  a  primary  partition. 

An  extended  partition  is  subdivided  into  extended  logical  disk  volumes,  each  consisting 
of  an  extended  boot  record  and  a  logical  block  device.  The  extended  boot  record  is  analo¬ 
gous  in  structure  to  the  partition  table  for  the  fixed  disk  as  a  whole;  it  contains  a  logical 
drive  table  describing  the  volume  and  a  pointer  to  the  next  extended  logical  volume.  The 
logical  block  device  is  an  image  of  a  normal  MS-DOS  disk,  including  a  master  block  (logi¬ 
cal  sector  0  containing  the  BPB  describing  the  device),  root  directory,  FAT,  and  files  area. 
Each  extended  volume  must  start  and  end  on  a  cylinder  boundary. 


Van  Wolverton 
Ray  Duncan 
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Appendix  B 
Critical  Error  Codes 


Critical  errors  are  returned  via  Interrupt  24H.  If  register  AL  bit  7  is  0,  then  the  error  was  a 
disk  error;  if  register  AL  bit  7  is  1,  then  the  error  was  a  nondisk  error.  The  upper  half  of  DI 
is  undefined;  the  lower  half  of  DI  contains  one  of  the  following  error-condition  codes: 


Code 

Description 

OOH 

Attempt  to  write  on  write-protected  disk 

OlH 

Unknown  drive  or  unit 

02H 

Drive  not  ready 

03H 

Invalid  command 

04H 

Data  error  (CRC  failed) 

05H 

Bad  request  structure  length 

06H 

Seek  error 

07H 

Unknown  media  type 

OSH 

Sector  not  found 

09H 

Printer  out  of  paper 

OAH 

Write  fault 

OBH 

Read  fault 

OCH 

General  failure 

OFH 

Invalid  disk  change 
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Appendix  C 
Extended  Error  Codes 


The  extended  error  codes  used  by  Interrupt  21H  functions  consist  of  four  separate  codes 
in  the  AX,  BH,  BL,  and  CH  registers.  These  codes  give  as  much  detail  as  possible  about  the 
error  and  suggest  how  the  issuing  program  should  respond. 


AX — Extended  Error  Code 

If  an  error  condition  occurs  in  response  to  an  Interrupt  21H  function  call,  the  carry  flag  is 
set  and  one  of  the  following  error  codes  is  returned  in  AX: 


Error 

Description 

Error 

Description 

OlH 

Invalid  function  code 

16H 

Invalid  disk  command 

02H 

File  not  found 

17H 

CRC  error 

03H 

Path  not  found 

18H 

Invalid  length  (disk  operation) 

04H 

Too  many  open  files  (no 

19H 

Seek  error 

handles  left) 

lAH 

Not  an  MS-DOS  disk 

05H 

Access  denied 

IBH 

Sector  not  found 

06H 

Invalid  handle 

ICH 

Out  of  paper 

07H 

Memory  control  blocks 

IDH 

Write  fault 

destroyed 

lEH 

Read  fault 

OSH 

Insufficient  memory 

IFH 

General  failure 

09H 

Invalid  memory  block  address 

20H 

Sharing  violation 

OAH 

Invalid  environment 

21H 

Lock  violation 

OBH 

Invalid  format 

22H 

Wrong  disk 

OCH 

Invalid  access  code 

23H 

FCB  unavailable 

ODH 

Invalid  data 

24H 

Sharing  buffer  overflow 

OEH 

Reserved 

25-31H 

Reserved 

OFH 

Invalid  drive 

32H 

Network  request  not  supported 

lOH 

Attempt  to  remove  the  current 

33H 

Remote  computer  not  listening 

directory 

34H 

Duplicate  name  on  network 

IIH 

Not  same  device 

35H 

Network  path  not  found 

12H 

No  more  files 

36H 

Network  busy 

13H 

Disk  is  write-protected 

37H 

Network  device  no  longer  exists 

14H 

Bad  disk  unit 

38H 

Net  BIOS  command  limit 

15H 

Drive  not  ready 

exceeded 

(more) 
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BH 


Error 

Description 

Error 

Description 

39H 

Network  adapter  hardware 

45H 

Net  BIOS  session  limit 

error 

exceeded 

3AH 

Incorrect  response  from 

46H 

Sharing  temporarily  paused 

network 

47H 

Network  request  not  accepted 

3BH 

Unexpected  network  error 

48H 

Print  or  disk  redirection  paused 

3CH 

Incompatible  remote  adapter 

49-4FH 

Reserved 

3DH 

Print  queue  full 

50H 

File  exists 

3EH 

Print  queue  not  full 

51H 

Reserved 

3FH 

Print  file  was  canceled  (not 

52H 

Cannot  make  directory  entry 

enough  space) 

53H 

Fail  on  Interrupt  24H 

40H 

Network  name  was  deleted 

54H 

Out  of  network  structures 

41H 

Access  denied 

55H 

Device  already  assigned 

42H 

Network  device  type  incorrect 

56H 

Invalid  password 

43H 

Network  name  not  found 

57H 

Invalid  parameter 

44H 

Network  name  limit  exceeded 

58H 

Network  data  fault 

—Error  Class 

BH  returns  a  code  that  describes  the  class  of  error  that  occurred: 

Class 

Description 

OlH  Out  of  a  resource,  such  as  storage  or  channels 

02H  Not  an  error,  but  a  temporary  situation  (such  as  a  locked  region  in  a  file)  that 

can  be  expected  to  end 
03H  Authorization  problem 

04H  An  internal  error  in  system  software 

05H  Hardware  failure 

06H  a  system  software  failure  not  the  fault  of  the  active  process  (could  be  caused 

by  missing  or  incorrect  configuration  files,  for  example) 

07H  Application  program  error 

OSH  File  or  item  not  found 

09H  File  or  item  of  invalid  format  or  type  or  otherwise  invalid  or  unsuitable 
OAH  File  or  item  interlocked 

OBH  Wrong  disk  in  drive,  bad  spot  on  disk,  or  other  problem  with  storage  medium 

OCH  Other  error 
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BL — Suggested  Action 

BL  returns  a  code  that  suggests  how  the  program  should  respond  to  the  error: 


Action  Description 

OlH  Retry,  then  prompt  user. 

02H  Retry  after  a  pause. 

03H  If  the  user  entered  data  such  as  a  drive  letter  or  filename,  prompt  for  it  again. 

04H  Terminate  with  cleanup. 

05H  Terminate  immediately.  The  system  is  so  unhealthy  that  the  program  should 
exit  as  soon  as  possible  without  taking  the  time  to  close  files  and  update 
indexes. 

06H  Error  is  informational. 

07H  Prompt  the  user  to  perform  some  action,  such  as  changing  disks,  then  retry  the 

operation. 


CH — Locus 

CH  returns  a  code  that  provides  additional  information  to  help  locate  the  area  involved  in 
the  failure.  This  code  is  particularly  useful  for  hardware  failures  (BH  =  05H). 


Locus  Description 

OlH  Unknown 

02H  Related  to  random-access  block  devices,  such  as  a  disk  drive 

03H  Related  to  network 

04H  Related  to  serial-access  character  devices,  such  as  a  printer 

05H  Related  to  random-access  memory 


Procedure 

Programs  should  handle  errors  by  noting  the  error  returned  in  AX  from  the  original  system 
call  and  then  invoking  Interrupt  21H  Function  59H  to  get  the  extended  error  information. 

If  no  extended  error  information  is  provided,  the  program  should  respond  to  the  original 
error  code. 

The  Function  59H  system  call  is  available  during  Interrupt  24H. 


Appendixes  1463 


Appendix  D:  ASCII  Character  Set  and  IBM  Extended  Character  Set 


Appendix  D 

ASCn  Character  Set  and 

IBM  Extended  Character  Set 


Number  Number 

Char  Dec  Hex  Control  Char  Dec  Hex  Control 


0 

00 

NUL 

(Null) 

# 

35 

23 

Q 

1 

01 

SOH 

(Start  of  heading) 

$ 

36 

24 

e 

2 

02 

STX 

(Start  of  text) 

% 

37 

25 

¥ 

3 

03 

ETX 

(End  of  text) 

& 

38 

26 

♦ 

4 

04 

EOT 

(End  of 

’ 

39 

27 

transmission) 

( 

40 

28 

5 

05 

ENQ 

(Enquiry) 

) 

41 

29 

♦ 

6 

06 

ACK 

(Acknowledge) 

* 

42 

2A 

• 

7 

07 

BEL 

(Bell) 

+ 

43 

2B 

□ 

8 

08 

BS 

(Backspace) 

, 

44 

2C 

o 

9 

09 

HT 

(Horizontal  tab) 

- 

45 

2D 

1! 

10 

OA 

LF 

(Linefeed) 

46 

2E 

<3 

11 

OB 

VT 

(Vertical  tab) 

/ 

47 

2F 

9 

12 

OC 

FF 

(Formfeed) 

0 

48 

30 

13 

CD 

CR 

(Carriage  return) 

1 

49 

31 

14 

OE 

SO 

(Shift  out) 

2 

50 

32 

15 

OF 

SI 

(Shift  in) 

3 

51 

33 

► 

16 

10 

DLE 

(Data  link  escape) 

4 

52 

34 

◄ 

17 

11 

DCl 

(Device  control  1) 

5 

53 

35 

t 

18 

12 

DC2 

(Device  control  2) 

6 

54 

36 

II 

19 

13 

DC3 

(Device  control  3) 

7 

55 

37 

20 

14 

DC4 

(Device  control  4) 

8 

56 

38 

§ 

21 

15 

NAK 

(Negative 

9 

57 

39 

acknowledge) 

58 

3A 

- 

22 

16 

SYN 

(Synchronous  idle) 

) 

59 

3B 

23 

17 

ETB 

(End  transmission 

< 

60 

3C 

block) 

= 

61 

3D 

t 

24 

18 

CAN 

(Cancel) 

> 

62 

3E 

25 

19 

EM 

(End  of  medium) 

? 

63 

3F 

26 

lA 

SUB 

(Substitute) 

@ 

64 

40 

*- 

27 

IB 

ESC 

(Escape) 

A 

65 

41 

•- 

28 

1C 

FS 

(File  separator) 

B 

66 

42 

4+ 

29 

ID 

GS 

(Group  separator) 

C 

67 

43 

A 

30 

IE 

RS 

(Record  separator) 

D 

68 

44 

T 

31 

IF 

US 

(Unit  separator) 

E 

69 

45 

< space > 

32 

20 

F 

70 

46 

j 

33 

21 

G 

71 

47 

» 

34 

22 

H 

72 

48 

(more) 
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Number  Number  Number 


Char 

Dec 

Hex 

Char 

Dec 

Hex  Control 

Char 

Dec 

Hex 

I 

73 

49 

z 

122 

7A 

171 

AB 

J 

74 

4A 

{ 

123 

7B 

1 

? 

172 

AC 

K 

75 

4B 

1 

1 

124 

7C 

i 

173 

AD 

L 

76 

4C 

} 

125 

7D 

« 

174 

AE 

M 

77 

4D 

~ 

126 

7E 

» 

175 

AF 

N 

78 

4E 

127 

7F  DEL 

176 

BO 

O 

79 

4F 

Q 

128 

80 

1 

177 

B1 

P 

80 

50 

ii 

129 

81 

i 

178 

B2 

Q 

81 

51 

e 

130 

82 

1 

179 

B3 

R 

82 

52 

a 

131 

83 

180 

B4 

S 

83 

53 

a 

132 

84 

=1 

181 

B5 

T 

84 

54 

a 

133 

85 

^1 

182 

B6 

U 

85 

55 

a 

134 

86 

H 

183 

B7 

V 

86 

56 

g 

135 

87 

=1 

184 

B8 

w 

87 

57 

e 

136 

88 

il 

185 

B9 

X 

88 

58 

e 

137 

89 

II 

186 

BA 

Y 

89 

59 

e 

138 

8A 

Tl 

187 

BB 

Z 

90 

5A 

i 

139 

8B 

J) 

188 

BC 

[ 

91 

5B 

i 

140 

8C 

JJ 

189 

BD 

\ 

92 

5C 

i 

141 

8D 

J 

190 

BE 

] 

93 

5D 

A 

142 

8E 

1 

191 

BF 

A 

94 

5E 

A 

143 

8F 

L 

192 

CO 

95 

5F 

E 

144 

90 

193 

Cl 

96 

60 

ae 

145 

91 

T 

194 

C2 

a 

97 

61 

R 

146 

92 

h 

195 

C3 

b 

98 

62 

6 

147 

93 

- 

196 

C4 

c 

99 

63 

6 

148 

94 

+ 

197 

C5 

d 

100 

64 

6 

149 

95 

h 

198 

C6 

e 

101 

65 

u 

150 

96 

1^ 

199 

C7 

f 

102 

66 

u 

151 

97 

It 

200 

C8 

g 

103 

67 

y 

151 

98 

ff 

201 

C9 

h 

104 

68 

6 

152 

99 

A 

202 

CA 

i 

105 

69 

u 

154 

9A 

if 

203 

CB 

j 

106 

6a 

c 

155 

9B 

1^ 

204 

CC 

k 

107 

6B 

£ 

156 

9C 

= 

205 

CD 

1 

108 

6C 

¥ 

157 

9D 

JL 

ir 

206 

CE 

m 

109 

6D 

I? 

158 

9E 

j_ 

207 

CF 

n 

110 

6E 

f 

159 

9F 

JL 

208 

DO 

o 

111 

6F 

a 

160 

AO 

T 

209 

D1 

P 

112 

70 

i 

161 

A1 

T 

210 

D2 

q 

113 

71 

6 

162 

A2 

IL 

211 

D3 

r 

114 

72 

ii 

163 

A3 

1= 

212 

D4 

s 

115 

73 

h 

l64 

A4 

r 

213 

D5 

t 

116 

74 

N 

165 

A5 

fT 

214 

D6 

u 

117 

75 

a 

166 

A6 

1 

215 

D7 

V 

118 

76 

fi 

167 

A7 

+ 

216 

D8 

w 

119 

77 

L 

168 

A8 

J 

217 

D9 

X 

120 

78 

169 

A9 

r 

218 

DA 

y 

121 

79 

- 

170 

AA 

1 

219 

DB 

(more) 
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Number  Number  Number 


Char 

Dec 

Hex 

Char 

Dec 

Hex 

Char 

Dec 

Hex 

■ 

220 

DC 

232 

E8 

r 

244 

F4 

1 

221 

DD 

0 

233 

E9 

j 

245 

F5 

1 

222 

DE 

n 

234 

EA 

•f 

246 

F6 

■ 

223 

DF 

6 

235 

EB 

« 

247 

F7 

a 

224 

EO 

00 

236 

EC 

0 

248 

F8 

P 

225 

El 

0 

237 

ED 

• 

249 

F9 

r 

226 

E2 

e 

238 

EE 

250 

FA 

ir 

227 

E3 

n 

239 

EF 

y 

251 

FB 

S 

228 

E4 

s 

240 

FO 

T1 

252 

FC 

a 

229 

E5 

+ 

241 

FI 

X 

253 

FD 

230 

E6 

> 

242 

F2 

■ 

254 

FE 

T 

231 

E7 

< 

243 

F3 

255 

FF 
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Appendix  E 
EBCDIC  Character  Set 


Number  Number  Number 


Char 

Dec 

Hex 

Char 

Dec 

Hex 

Char  Dec 

Hex 

NUL 

0 

00 

41 

29 

82 

52 

SOH 

1 

01 

SM 

42 

2A 

83 

53 

STX 

2 

02 

CU2 

43 

2B 

84 

54 

ETX 

3 

03 

44 

2C 

85 

55 

PF 

4 

04 

ENQ 

45 

2D 

86 

56 

HT 

5 

05 

ACK 

46 

2E 

87 

57 

LC 

6 

06 

BEL 

47 

2F 

88 

58 

DEL 

7 

07 

48 

30 

89 

59 

GE 

8 

08 

49 

31 

! 

90 

5A 

RLE 

9 

09 

SYN 

50 

32 

$ 

91 

5B 

SMM 

10 

OA 

51 

33 

* 

92 

5C 

VT 

11 

OB 

PN 

52 

34 

) 

93 

5D 

FF 

12 

OC 

RS 

53 

35 

j 

94 

5E 

CR 

13 

OD 

UC 

54 

36 

— 1 

95 

5F 

SO 

14 

OE 

EOT 

55 

37 

- 

96 

60 

SI 

15 

OF 

56 

38 

/ 

97 

61 

DLE 

16 

10 

57 

39 

98 

62 

DCl 

17 

11 

58 

3A 

99 

63 

DC2 

18 

12 

CU3 

59 

3B 

100 

64 

TM 

19 

13 

DC4 

60 

3C 

101 

65 

RES 

20 

14 

NAK 

61 

3D 

102 

66 

NL 

21 

15 

62 

3E 

103 

67 

BS 

22 

16 

SUB 

63 

3F 

104 

68 

IL 

23 

17 

Sp 

64 

40 

105 

69 

CAN 

24 

18 

65 

41 

1 

1 

106 

6A 

EM 

25 

19 

66 

42 

, 

107 

6B 

CC 

26 

lA 

67 

43 

% 

108 

6C 

CUl 

27 

IB 

68 

44 

109 

6D 

IFS 

28 

1C 

69 

45 

> 

110 

6E 

IGS 

29 

ID 

70 

46 

111 

6F 

IRS 

30 

IE 

71 

47 

112 

70 

lUS 

31 

IF 

72 

48 

113 

71 

DS 

32 

20 

73 

49 

114 

72 

SOS 

33 

21 

<c 

74 

4A 

115 

73 

FS 

34 

22 

75 

4B 

116 

74 

35 

23 

< 

76 

4C 

117 

75 

BYP 

36 

24 

( 

77 

4D 

118 

76 

LF 

37 

25 

+ 

78 

4E 

119 

77 

ETB 

38 

26 

1 

79 

4F 

120 

78 

ESC 

39 

27 

& 

80 

50 

121 

79 

40 

28 

81 

51 

122 

7A 
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Number  Number  Number 


Char 

Dec 

Hex 

Char 

Dec 

Hex 

Char 

Dec 

Hex 

# 

123 

7B 

y 

168 

A8 

N 

213 

D5 

@ 

124 

7C 

z 

169 

A9 

O 

214 

D6 

1 

125 

7D 

170 

AA 

P 

215 

D7 

= 

126 

7E 

171 

AB 

Q 

216 

D8 

ti 

127 

7F 

172 

AC 

R 

217 

D9 

128 

80 

173 

AD 

218 

DA 

a 

129 

81 

174 

AE 

219 

DB 

b 

130 

82 

175 

AF 

220 

DC 

c 

131 

83 

176 

BO 

221 

DD 

d 

132 

84 

177 

B1 

222 

DE 

e 

133 

85 

178 

B2 

223 

DF 

f 

134 

86 

179 

B3 

\ 

224 

EO 

g 

135 

87 

180 

B4 

225 

El 

h 

136 

88 

181 

B5 

S 

226 

E2 

i 

137 

89 

182 

B6 

T 

227 

E3 

138 

8A 

183 

B7 

U 

228 

E4 

139 

8B 

184 

B8 

V 

229 

E5 

140 

8C 

185 

B9 

w 

230 

E6 

141 

8D 

186 

BA 

X 

231 

E7 

142 

8E 

187 

BB 

Y 

232 

E8 

143 

8F 

188 

BC 

Z 

233 

E9 

144 

90 

189 

BD 

234 

EA 

j 

145 

91 

190 

BE 

235 

EB 

k 

146 

92 

191 

BF 

H 

236 

EC 

1 

147 

93 

{ 

192 

CO 

237 

ED 

m 

148 

94 

A 

193 

Cl 

238 

EE 

n 

149 

95 

B 

194 

C2 

239 

EF 

o 

150 

96 

C 

195 

C3 

0 

240 

FO 

P 

151 

97 

D 

196 

C4 

1 

241 

FI 

q 

152 

98 

E 

197 

C5 

2 

242 

F2 

r 

153 

99 

F 

198 

C6 

3 

243 

F3 

154 

9A 

G 

199 

C7 

4 

244 

F4 

155 

9B 

H 

200 

C8 

5 

245 

F5 

156 

9C 

I 

201 

C9 

6 

246 

F6 

157 

9D 

202 

CA 

7 

247 

F7 

158 

9E 

203 

CB 

8 

248 

F8 

159 

9F 

J’ 

204 

CC 

9 

249 

F9 

160 

AO 

205 

CD 

1 

250 

FA 

161 

A1 

V 

206 

CE 

251 

FB 

s 

162 

A2 

207 

CF 

252 

FC 

t 

163 

A3 

I 

208 

DO 

253 

FD 

u 

164 

A4 

J 

209 

D1 

254 

FE 

V 

165 

A5 

K 

210 

D2 

EO 

255 

FF 

w 

166 

a6 

L 

211 

D3 

X 

167 

A7 

M 

212 

D4 
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Appendix  F 

ANSI.SYS  Key  and  Extended  Key  Codes 


The  following  escape  sequence  allows  redefinition  of  keyboard  keys  to  a  specified  string. 

lESC[code\string, . . .  p 

where: 

string  is  either  the  ASCII  code  for  a  single  character  or  a  string  contained  in  quotation 
marks.  For  example,  both  65  and  "A"  can  be  used  to  represent  an  uppercase  A. 
code  is  one  or  more  of  the  following  values  that  represent  keyboard  keys.  Semi¬ 
colons  shown  in  this  table  must  be  entered  in  addition  to  the  required  semi¬ 
colons  in  the  command  line. 


Key 

Code 

Alone 

Shift- 

Ctrl- 

Alt- 

FI 

0;59 

0;84 

0;94 

0;104 

F2 

0;60 

0;85 

0;95 

0;105 

F3 

0;6l 

0;86 

0;96 

0;106 

F4 

0;62 

0;87 

0;97 

0;107 

F5 

0;63 

0;88 

0;98 

0;108 

F6 

0;64 

0;89 

0;99 

0;109 

F7 

0;65 

0;90 

OjlOO 

0;110 

F8 

0;66 

0;91 

0;101 

0;111 

F9 

0;67 

0;92 

0;102 

0;112 

FIO 

0;68 

0;93 

0;103 

0;113 

Home 

0;71 

55 

0;119 

- 

Up  Arrow 

0;72 

56 

- 

- 

PgUp 

0;73 

57 

0;132 

- 

Left  Arrow 

0;75 

52 

0;115 

- 

Down  Arrow 

0;77 

54 

0;116 

— 

End 

0;79 

49 

0;117 

— 

Down  Arrow 

0;80 

50 

- 

— 

Pg  Dn 

0;81 

51 

0;118 

— 

Ins 

0;82 

48 

- 

— 

Del 

0;83 

46 

- 

— 

PrtSc 

- 

— 

0;114 

— 

A 

97 

65 

1 

0;30 

(more) 
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Key 

Code 

Alone 

Shift- 

Ctrl- 

Alt- 

B 

98 

66 

2 

0;48 

c 

99 

67 

3 

0;46 

D 

100 

68 

4 

0;32 

E 

101 

69 

5 

0;18 

F 

102 

70 

6 

0;33 

G 

103 

71 

7 

0;34 

H 

104 

72 

8 

0;35 

I 

105 

73 

9 

0;23 

j 

106 

74 

10 

0;36 

K 

107 

75 

11 

0;37 

L 

108 

76 

12 

0;38 

M 

109 

77 

13 

0;50 

N 

no 

78 

14 

0;49 

O 

111 

79 

15 

0;24 

P 

112 

80 

16 

0;25 

Q 

113 

81 

17 

0;16 

R 

114 

82 

18 

0;19 

S 

115 

83 

19 

0;31 

T 

116 

84 

20 

0;20 

U 

117 

85 

21 

0;22 

V 

118 

86 

22 

0;47 

W 

119 

87 

23 

0;17 

X 

120 

88 

24 

0;45 

Y 

121 

89 

25 

0;21 

Z 

122 

90 

26 

0;44 

1 

49 

33 

- 

0;120 

2 

50 

64 

- 

0;121 

3 

51 

35 

- 

0;122 

4 

52 

36 

- 

0;123 

5 

53 

37 

- 

0;124 

6 

54 

94 

- 

0;125 

7 

55 

38 

- 

0;126 

8 

56 

42 

- 

0;127 

9 

57 

40 

- 

0;128 

0 

48 

41 

- 

0;129 

- 

45 

95 

- 

0;130 

= 

61 

43 

- 

0;131 

Tab 

9 

0;15 

- 

- 

Null 

0;3 

- 

- 

- 
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Appendix  G 

File  Control  Block  (FCB)  Structure 


Figures  G-1  and  G-2  (memory  block  diagrams)  and  Tables  G-1  and  G-2  describe  the  struc¬ 
ture  of  normal  and  extended  file  control  blocks  (FCBs). 


Offset 

OOH 

OlH 


09H 

OCH 

OEM 

lOH 

14H 

16H 

18H 


20H 

21H 


Drive  identiBer 


Filename 


File  extension 


Current  block  number 


Record  size  (bytes) 


File  size  (bytes) 


Date  stamp 


Time  stamp 


Reserved 


Current  record  number 


Random  record  number 


Figure  G-1.  Structure  of  a  normal file 
control  block. 
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Table  G>1.  Elements  of  a  Normal  File  Control  Block. 


Element 

Maintained 

by 

Comments 

Drive  identifier 

Program 

Designates  the  drive  on  which  the  file  to  be 
opened  or  created  resides  (0  =  default  drive,  1  = 
drive  A,  2  =  drive  B,  and  so  on).  If  the  application 
supplies  a  zero  in  this  byte,  MS-DOS  alters  the 
byte  during  the  open  or  create  operation  to 
reflect  the  actual  drive  used. 

Filename 

Program 

Standard  eight-character  filename;  must  be  left 
justified  and  must  be  padded  with  blanks  if  fewer 
than  eight  characters.  A  device  name  (for  exam¬ 
ple,  PRN)  can  be  used;  there  is  no  colon  after  a 
device  name. 

File  extension 

Program 

Three-character  file  extension;  must  be  left  justi¬ 
fied  and  must  be  padded  with  blanks  if  fewer 
than  three  characters. 

Current  block 
number 

Program 

Zero  when  the  file  is  opened;  the  current  block 
number  and  the  current  record  number  com¬ 
bined  make  up  the  record  pointer  during  sequen¬ 
tial  file  access. 

Record  size 

Program 

Set  to  128  when  the  file  is  opened  or  created;  the 
program  can  modify  the  field  afterward  to  any 
desired  record  size.* 

File  size 

MS-DOS 

The  size  of  the  file  in  bytes;  the  first  2  bytes  of  this 
4-byte  field  are  the  least  significant  bytes  of  the 
file  size. 

Date  stamp 

MS-DOS 

The  date  of  the  last  write  operation  on  the  file;  fol- 

lows  the  same  format  used  by  Interrupt  21H  file 
handle  Function  57H  (Get/Set  Time  and  Date): 


Bits 

Contents 

9-15 

Year  (relative  to  1980) 

5-8 

Month  (1-12) 

0-4 

Day  of  month  (1-31) 

Time  stamp  MS-DOS  The  time  of  the  last  write  operation  on  the  file;  fol¬ 

lows  the  same  format  used  by  Interrupt  21H  file 
handle  Function  57H  (Get/Set  Time  and  Date): 

Bits  Contents 

11-15  Hours  (0-23) 

5-10  Minutes  (0-59) 

0-4  Number  of  2-second 

increments  (0-29) 

(more) 
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Table  G-1.  Continued. 


Maintained 

Element 

by 

Comments 

Current  record 

Program 

Limited  to  the  range  0  through  127;  there  are 

number 

128  records  per  block.  The  beginning  of  a  file  is 
record  0  of  block  0.  Together  with  the  current 
block  number,  this  field  constitutes  the  record 
pointer  used  during  sequential  read  and  write 
operations.  MS-DOS  does  not  automatically 
initialize  this  field  when  a  file  is  opened. 

Random  record 

Program 

Identifies  the  record  to  be  transferred  by  the  Inter- 

pointer 

rupt  21H  random  record  functions  21H,  22H, 

27H,  and  28H;  if  the  record  size  is  64  bytes  or 
larger,  only  the  first  3  bytes  of  this  field  are  used. 
MS-DOS  updates  this  field  after  random  block 
reads  and  writes  (Functions  27H  and  28H)  but 
not  after  random  record  reads  and  writes 
(Functions  21H  and  22H). 

*  If  the  record  size  is  made  larger  than  128  bytes,  the  default  data  transfer  area  (DTA)  in  the  program  segment 
prefix  (PSP)  cannot  be  used  because  it  will  collide  with  the  program’s  own  code  or  data. 

Table  G-2.  Additional  Elements  of  an  Extended  File  Control  Block. 

Maintained 

Element 

by 

Comments 

Extended  FCB  flag 
File  attribute  byte 


Program  OFFH  tells  MS-DOS  this  is  an  extended  (44-byte) 
FCB. 

Program  Must  be  initialized  by  the  application  when  an 
extended  FCB  is  used  to  open  or  create  a  file. 
The  bits  of  this  field  have  the  following 
significance: 


Bit 

0 

1 

2 

3 

4 

5 

6 
7 


Meaning 

Read-only 

Hidden 

System 

Volume  label 

Directory 

Archive 

Reserved 

Reserved 
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Offset 


OOH 

OlH 


06H 

07H 

OSH 


lOH 

13H 

15H 

17H 

IBH 

IDH 

IFH 


27H 

28H 


Extended  FCB  flag  (OFFH) 

Reserved 

File  attribute  byte 

Drive  identifier 

Filename 

File  extension 

Current  block  number 

Record  size  (bytes) 

File  size  (bytes) 

Date  stamp 

Time  stamp 

Reserved 

Current  record  number 

•  Random  record  number 

Figure  G-2.  Structure  of  an  extended file 
control  block. 
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Appendix  H 

Program  Segment  Prefix  (PSP)  Structure 


Offset 
OOH  (0) 
02H  (2) 

04H  (4) 
OSH  (5) 

OAH  (10) 
OEH  (14) 
12H  (18) 
16H  (22) 

2CH  (44) 
2EH  (46) 


50H  (80) 
53H  (83) 

5CH  (92) 


6CH  (108) 


80H  (128) 

FFH  (255) 


Size 

(in 

bytes)  Contents 


22 


16 


20 


INT  20H  instruction 


Address  of  last  segment 
allocated  to  program 


Reserved;  normally  0 


Long  call  to  MS-DOS  function  dispatcher 


Terminate  program  interrupt  vector 
(Interrupt  22H) 


Ctrl-C  handler  interrupt  vector 
(Interrupt  23H) 


Critical  error  handler  interrupt  vector 
(Interrupt  24H) 


Reserved 


Segment  address  of  environment 


Reserved 


INT  21H,  RETF  instructions 


Reserved 


Default  file  control  block  1 


Default  file  control  block  2 
(overlaid  if  FCB  1  opened) 


Command  tail  and  default  DTA 


Figure  H-1  (memory  block  diagram) 
illustrates  the  structure  of  the  pro¬ 
gram  segment  prefix  (PSP). 


Figure  H-1.  Structure  of  the  program  segment  prefix. 
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Appendix  I 

8086/8088/80286/80386  Instruction  Sets 

The  8086/8088  Instruction  Set 


Mnemonic 

Description 

Mnemonic 

Description 

AAA 

ASCII  adjust  after  addition 

JB 

Jump  on  below 

AAD 

ASCII  adjust  before  division 

JBE 

Jump  on  below  or  equal 

AAM 

ASCII  adjust  after  multiplication 

JC 

Jump  on  carry 

AAS 

ASCII  adjust  after  subtraction 

JCXZ 

Jump  on  CX  zero 

ADC 

Add  with  carry 

JE 

Jump  on  equal 

ADD 

Add 

JG 

Jump  on  greater 

AND 

Logical  AND 

JGE 

Jump  on  greater  or  equal 

CALL 

Call  procedure 

JL 

Jump  on  less  than 

CBW 

Convert  byte  to  word 

JLE 

Jump  on  less  than  or  equal 

CLC 

Clear  carry  flag 

JMP 

Jump  unconditionally 

CLD 

Clear  direction  flag 

JNA 

Jump  on  not  above 

CLI 

Clear  interrupt  flag 

JNAE 

Jump  on  not  above  or  equal 

CMC 

Complement  carry  flag 

JNB 

Jump  on  not  below 

CMP 

Compare 

JNBE 

Jump  on  not  below  or  equal 

CMPS 

Compare  string 

JNC 

Jump  on  no  carry 

CMPSB 

Compare  byte  string 

JNE 

Jump  on  not  equal 

CMPSW 

Compare  word  string 

JNG 

Jump  on  not  greater 

CWD 

Convert  word  to  doubleword 

JNGE 

Jump  on  not  greater  or  equal 

DAA 

Decimal  adjust  for  addition 

JNL 

Jump  on  not  less  than 

DAS 

Decimal  adjust  for  subtraction 

JNLE 

Jump  on  not  less  than  or  equal 

DEC 

Decrement  by  1 

JNO 

Jump  on  not  overflow 

DIV 

Unsigned  divide 

JNP 

Jump  on  not  parity 

ESC 

Escape 

JNS 

Jump  on  not  sign 

HLT 

Halt 

JNZ 

Jump  on  not  zero 

IDIV 

Integer  divide 

JO 

Jump  on  overflow 

IMUL 

Integer  multiply 

JP 

Jump  on  parity 

IN 

Input  from  port 

JPE 

Jump  on  parity  even 

INC 

Increment  by  1 

JPO 

Jump  on  parity  odd 

INT 

Call  to  interrupt  procedure 

JS 

Jump  on  sign 

INTO 

Interrupt  on  overflow 

JZ 

Jump  on  zero 

IRET 

Interrupt  on  return 

LAHF 

Load  AH  with  flags 

JA 

Jump  on  above 

LDS 

Load  pointer  into  DS 

JAE 

Jump  on  above  or  equal 

LEA 

Load  effective  address 

(more) 
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Mnemonic 

Description 

Mnemonic 

Description 

LES 

Load  pointer  into  ES 

REPNE 

Repeat  while  not  equal 

LOCK 

Lock  the  bus 

REPNZ 

Repeat  while  not  zero 

LODS 

Load  string 

REPZ 

Repeat  while  zero 

LODSB 

Load  byte  (string) 

RET 

Return 

LODSW 

Load  word  (string) 

ROL 

Rotate  left 

LOOP 

Loop 

ROR 

Rotate  right 

LOOPE 

Loop  while  equal 

SAHF 

Store  AH  into  flags 

LOOPNE 

Loop  while  not  equal 

SAL 

Shift  arithmetic  left 

LOOPNZ 

Loop  while  not  zero 

SAR 

Shift  arithmetic  right 

LOOPZ 

Loop  while  zero 

SBB 

Subtract  with  borrow 

MOV 

Move  data 

SCAS 

Scan  string 

MOVS 

Move  data  from  string  to  string 

SCASB 

Scan  byte  (string) 

MOVSB 

Move  byte  (string) 

SCASW 

Scan  word  (string) 

MOVSW 

Move  word  (string) 

SHL 

Shift  logical  left 

MUL 

Multiply 

SHR 

Shift  logical  right 

NEC 

Negate 

STC 

Set  carry  flag 

NOP 

No  operation 

STD 

Set  direction  flag 

NOT 

Logical  NOT 

STI 

Set  interrupt  flag 

OR 

Logical  OR 

STOS 

Store  string 

OUT 

Output  to  port 

STOSB 

Store  byte  (string) 

POP 

Pop  top  of  stack 

STOSW 

Store  word  (string) 

POPE 

Pop  stack  into  flags 

SUB 

Subtract 

PUSH 

Push  onto  stack 

TEST 

Logical  compare 

PUSHF 

Push  flags  onto  stack 

WAIT 

Enter  wait  state 

RCL 

Rotate  through  carry  left 

XCHG 

Exchange 

RCR 

Rotate  through  carry  right 

XLAT 

Translate 

REP 

Repeat 

XOR 

Exclusive  OR 

REPE 

Repeat  while  equal 

The  80286  Instruction  Set 


Mnemonic 

Description 

Mnemonic 

Description 

AAA 

ASCII  adjust  after  addition 

AND 

Logical  AND 

AAD 

ASCII  adjust  before  division 

ARPL 

Adjust  RPL  field  of  selector 

AAM 

ASCII  adjust  after  multiplication 

BOUND 

Check  array  index  against  bounds 

AAS 

ASCII  adjust  after  subtraction 

CALL 

Call  procedure 

ADC 

Add  with  carry 

CBW 

Convert  byte  to  word 

ADD 

Add 

CLC 

Clear  carry  flag 

(more) 
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Mnemonic 

Description 

Mnemonic 

Description 

CLD 

Clear  direction  flag 

JNE 

Jump  on  not  equal 

CLI 

Clear  interrupt  flag 

JNG 

Jump  on  not  greater 

CUTS 

Clear  task  switched  flag 

JNGE 

Jump  on  not  greater  or  equal 

CMC 

Complement  carry  flag 

JNL 

Jump  on  not  less  than 

CMP 

Compare 

JNLE 

Jump  on  not  less  than  or  equal 

CMPS 

Compare  string 

JNO 

Jump  on  not  overflow 

CMPSB 

Compare  byte  string 

JNP 

Jump  on  not  parity 

CMPSW 

Compare  word  string 

JNS 

Jump  on  not  sign 

CWD 

Convert  word  to  doubleword 

JNZ 

Jump  on  not  zero 

DAA 

Decimal  adjust  for  addition 

JO 

Jump  on  overflow 

DAS 

Decimal  adjust  for  subtraction 

JP 

Jump  on  parity 

DEC 

Decrement  by  1 

JPE 

Jump  on  parity  even 

DIV 

Unsigned  divide 

JPO 

Jump  on  parity  odd 

ENTER 

Make  stack  frame 

JS 

Jump  on  sign 

(for  procedure  parameters) 

JZ 

Jump  on  zero 

ESC 

Escape 

LAHF 

Load  AH  with  flags 

HLT 

Halt 

LAR 

Load  access-rights  byte 

IDIV 

Integer  divide 

IDS 

Load  pointer  into  DS 

IMUL 

Integer  multiply 

LEA 

Load  effective  address 

IN 

Input  from  port 

LEAVE 

High-level  procedure  exit 

INC 

Increment  by  1 

LES 

Load  pointer  into  ES 

INS 

Input  string  from  port 

LGDT 

Load  global  descriptor  table 

INT 

Call  to  interrupt  procedure 

LIDT 

Load  interrupt  descriptor  table 

INTO 

Interrupt  on  overflow 

LLDT 

Load  local  descriptor  table 

IRET 

Interrupt  on  return 

LMSW 

Load  machine  status  word 

JA 

Jump  on  above 

LOCK 

Lock  the  bus 

JAE 

Jump  on  above  or  equal 

LCDS 

Load  string 

JB 

Jump  on  below 

LODSB 

Load  byte  (string) 

JBE 

Jump  on  below  or  equal 

LODSW 

Load  word  (string) 

JC 

Jump  on  carry 

LOOP 

Loop 

JCXZ 

Jump  on  CX  zero 

LOOPE 

Loop  while  equal 

JE 

Jump  on  equal 

LOOPNE 

Loop  while  not  equal 

JG 

Jump  on  greater 

LOOPNZ 

Loop  while  not  zero 

JGE 

Jump  on  greater  or  equal 

LOOPZ 

Loop  while  zero 

JL 

Jump  on  less  than 

LSL 

Load  segment  limit 

JLE 

Jump  on  less  than  or  equal 

LTR 

Load  task  roister 

JMP 

Jump  unconditionally 

MOV 

Move  data 

JNA 

Jump  on  not  above 

MOVS 

Move  data  from  string  to  string 

JNAE 

Jump  on  not  above  or  equal 

MOVSB 

Move  byte  (string) 

JNB 

Jump  on  not  below 

MOVSW 

Move  word  (string) 

JNBE 

Jump  on  not  below  or  equal 

MUL 

Multiply 

JNC 

Jump  on  no  carry 

NEG 

Negate 

(more) 
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Mnemonic 

Description 

Mnemonic 

Description 

NOP 

No  operation 

SCAS 

Scan  string 

NOT 

Logical  NOT 

SCASB 

Scan  byte  (string) 

OR 

Logical  OR 

SCASW 

Scan  word  (string) 

OUT 

Output  to  port 

SGDT 

Store  global  descriptor  table 

OUTS 

Output  string  to  port 

SHL 

Shift  logical  left 

POP 

Pop  top  of  stack 

SHR 

Shift  logical  right 

POPA 

Pop  eight  l6-bit  registers 

SIDT 

Store  interrupt  descriptor  table 

POPF 

Pop  stack  into  flags 

SLOT 

Store  local  descriptor  table 

PUSH 

Push  onto  stack 

SMSW 

Store  machine  status  word 

PUSHA 

Push  eight  l6-bit  registers 

STC 

Set  carry  flag 

PUSHF 

Push  flags  onto  stack 

STD 

Set  direction  flag 

RCL 

Rotate  through  carry  left 

STI 

Set  interrupt  flag 

RCR 

Rotate  through  carry  right 

STOS 

Store  string 

REP 

Repeat 

STOSB 

Store  byte  (string) 

REPE 

Repeat  while  equal 

STOSW 

Store  word  (string) 

REPNE 

Repeat  while  not  equal 

STR 

Store  task  register 

REPNZ 

Repeat  while  not  zero 

SUB 

Subtract 

REPZ 

Repeat  while  zero 

TEST 

Logical  compare 

RET 

Return 

VERR 

Verify  a  segment  for  reading 

ROL 

Rotate  left 

VERW 

Verify  a  segment  for  writing 

ROR 

Rotate  right 

WAIT 

Enter  wait  state 

SAHF 

Store  AH  into  flags 

XCHG 

Exchange 

SAL 

Shift  arithmetic  left 

XLAT 

Translate 

SAR 

Shift  arithmetic  right 

XOR 

Exclusive  OR 

SBB 

Subtract  with  borrow 

The  80386  Instruction  Set 


Mnemonic 

Description 

Mnemonic 

Description 

AAA 

ASCII  adjust  after  addition 

BSF 

Bit  scan  forward 

AAD 

ASCII  adjust  before  division 

BSR 

Bit  scan  reverse 

AAM 

ASCII  adjust  after  multiplication 

BT 

Bit  test 

AAS 

ASCII  adjust  after  subtraction 

BTC 

Bit  test  and  complement 

ADC 

Add  with  carry 

BTR 

Bit  test  and  reset 

ADD 

Add 

BTS 

Bit  test  and  set 

AND 

Logical  AND 

CALL 

Call  procedure 

ARPL 

Adjust  RPL  field  of  selector 

CBW 

Convert  byte  to  word 

BOUND 

Check  array  index  against  bounds 

CDQ 

Convert  doubleword  to  quad  word 

(more) 
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Mnemonic 

Description 

Mnemonic 

Description 

CLC 

Clear  carry  flag 

JMP 

Jump  unconditionally 

CLD 

Clear  direction  flag 

JNA 

Jump  on  not  above 

CLI 

Clear  interrupt  flag 

JNAE 

Jump  on  not  above  or  equal 

CLTS 

Clear  task  switched  flag 

JNB 

Jump  on  not  below 

CMC 

Complement  carry  flag 

JNBE 

Jump  on  not  below  or  equal 

CMP 

Compare 

JNC 

Jump  on  no  carry 

CMPS 

Compare  string 

JNE 

Jump  on  not  equal 

CMPSB 

Compare  byte  string 

JNG 

Jump  on  not  greater 

CMPSD 

Compare  doubleword  string 

JNGE 

Jump  on  not  greater  or  equal 

CMPSW 

Compare  word  string 

JNL 

Jump  on  not  less  than 

CWD 

Convert  word  to  doubleword 

JNLE 

Jump  on  not  less  than  or  equal 

DAA 

Decimal  adjust  for  addition 

JNO 

Jump  on  not  overflow 

DAS 

Decimal  adjust  for  subtraction 

JNP 

Jump  on  not  parity 

DEC 

Decrement  by  1 

JNS 

Jump  on  not  sign 

DIV 

Unsigned  divide 

JNZ 

Jump  on  not  zero 

ENTER 

Make  stack  frame 

JO 

Jump  on  overflow 

(for  procedure  parameters) 

JP 

Jump  on  parity 

ESC 

Escape 

JPE 

Jump  on  parity  even 

HLT 

Halt 

JPO 

Jump  on  parity  odd 

IDIV 

Integer  divide 

JS 

Jump  on  sign 

IMUL 

Integer  multiply 

JZ 

Jump  on  zero 

IN 

Input  from  port 

LAHF 

Load  AH  with  flags 

INC 

Increment  by  1 

LAR 

Load  access-rights  byte 

INS 

Input  string  from  port 

IDS 

Load  pointer  into  DS 

INSD 

Input  doubleword  from  port 

LEA 

Load  effective  address 

INT 

Call  to  interrupt  procedure 

LEAVE 

High-level  procedure  exit 

INTO 

Interrupt  on  overflow 

LES 

Load  pointer  into  ES 

IRET 

Interrupt  on  return 

LFS 

Load  pointer  into  FS 

IRETD 

Interrupt  return  to 

LGDT 

Load  global  descriptor  table 

virtual  8086  mode 

LGS 

Load  pointer  into  GS 

JA 

Jump  on  above 

LIDT 

Load  interrupt  descriptor  table 

JAE 

Jump  on  above  or  equal 

LLDT 

Load  local  descriptor  table 

JB 

Jump  on  below 

LMSW 

Load  machine  status  word 

JBE 

Jump  on  below  or  equal 

LOCK 

Lock  the  bus 

JC 

Jump  on  carry 

LODS 

Load  string 

JCXZ 

Jump  on  CX  zero 

LODSB 

Load  byte  (string) 

JE 

Jump  on  equal 

LODSD 

Load  doubleword  (string) 

JECXZ 

Jump  on  ECX  zero 

LODSW 

Load  word  (string) 

JG 

Jump  on  greater 

LOOP 

Loop 

JGE 

Jump  on  greater  or  equal 

LOOPE 

Loop  while  equal 

JL 

Jump  on  less  than 

LOOPNE 

Loop  while  not  equal 

JLE 

Jump  on  less  than  or  equal 

LOOPNZ 

Loop  while  not  zero 

(more) 
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Mnemonic 

Description 

Mnemonic 

Description 

LOOPZ 

Loop  while  zero 

ROL 

Rotate  left 

LSL 

Load  segment  limit 

ROR 

Rotate  right 

LSS 

Load  pointer  into  SS 

SAHF 

Store  AH  into  flags 

LTR 

Load  task  register 

SAL 

Shift  arithmetic  left 

MOV 

Move  data 

SAR 

Shift  arithmetic  right 

MOVS 

Move  data  from  string  to  string 

SBB 

Subtract  with  borrow 

MOVSB 

Move  byte  (string) 

SCAS 

Scan  string 

MOVSD 

Move  doubleword  (string) 

SCASB 

Scan  byte  (string) 

MOVSW 

Move  word  (string) 

SCASD 

Scan  doubleword  (string) 

MOVSX 

Move  with  sign  extend 

SCASW 

Scan  word  (string) 

MOVZX 

Move  with  zero  extend 

SET 

Byte  set  on  condition 

MUL 

Multiply 

SGDT 

Store  global  descriptor  table 

NEC 

Negate 

SHL 

Shift  logical  left 

NOP 

No  operation 

SHLD 

Double  precision  shift  left 

NOT 

Logical  NOT 

SHR 

Shift  logical  right 

OR 

Logical  OR 

SHRD 

Double  precision  shift  right 

OUT 

Output  to  port 

SIDT 

Store  interrupt  descriptor  table 

OUTS 

Output  string  to  port 

SLOT 

Store  local  descriptor  table 

POP 

Pop  top  of  stack 

SMSW 

Store  machine  status  word 

POPA 

Pop  eight  l6-bit  registers 

STC 

Set  carry  flag 

POPAD 

Pop  eight  32-bit  registers 

STD 

Set  direction  flag 

POPF 

Pop  stack  into  flags 

STI 

Set  interrupt  flag 

POPFD 

Loads  doubleword  into  EFLAGS 

STOS 

Store  string 

PUSH 

Push  onto  stack 

STOSB 

Store  byte  (string) 

PUSHA 

Push  eight  l6-bit  registers 

STOSD 

Store  doubleword  (string) 

PUSHAD 

Push  eight  32-bit  registers 

STOSW 

Store  word  (string) 

PUSHED 

Push  EFLAGS 

STR 

Store  task  register 

PUSHF 

Push  flags  onto  stack 

SUB 

Subtract 

RCL 

Rotate  through  carry  left 

TEST 

Logical  compare 

RCR 

Rotate  through  carry  right 

VERR 

Verify  a  segment  for  reading 

REP 

Repeat 

VERW 

Verify  a  segment  for  writing 

REPE 

Repeat  while  equal 

WAIT 

Enter  wait  state 

REPNE 

Repeat  while  not  equal 

XCHG 

Exchange 

REPNZ 

Repeat  while  not  zero 

XLAT 

Translate 

REPZ 

Repeat  while  zero 

XOR 

Exclusive  OR 

RET 

Return 
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Common  MS-DOS  Filename  Extensions 


The  Microsoft  systems  programs  and  language  products  commonly  use  the  following  file¬ 
name  extensions: 


Extension 

Program/System 

Description 

.@@@ 

MS-DOS 

Backup  ID  file 

.$$$ 

EDLIN 

Backup  filename  if  out  of  disk  space;  error 
condition 

.ASC 

Generic 

ASCII  text  file 

.ASM 

MASM 

Assembly-language  source  code 

•BAK 

Generic 

Backup  file 

.BAS 

BASIC 

BASIC  language  source  code 

•BAT 

MS-DOS 

Batch  file  (contains  MS-DOS  command  lines) 

•BIN 

Generic 

Binary  file 

.c 

c 

C  language  source  code 

.CAL 

Windows 

Calendar  file 

•COB 

COBOL 

COBOL  language  source  code 

■COD 

Generic 

Object  listing  file 

•COM 

MS-DOS 

Executable  program  file 

.CRD 

Windows 

Cardfile  file 

.CRF 

MASM 

Cross-reference  file 

.DAT 

Generic 

Data  file 

.DBG 

COBOL 

Debug  file 

.DEF 

Windows 

Module  definition  file 

.DOC 

Generic 

Documentation  or  document  file 

.DRV 

Generic 

Driver  file 

.ERR 

Generic 

Error  file 

.EXE 

MS-DOS 

Executable  program  file 

.ENT 

Generic 

Font  file 

.EON 

Generic 

Font  file 

.FOR 

FORTRAN 

FORTRAN  language  source  code 

.GRB 

Windows 

Grab  file  (snapshot) 

.H 

C 

Include  file 

.HEX 

MS-DOS 

INTEL  hexadecimal  format  file 

.HLP 

Generic 

Help  file 

.INC 

Generic 

Include  file 

.INI 

Windows 

Initialization  file 

(more) 
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Extension 

Program/System 

Description 

.INT 

COBOL 

Object  file 

.LIB 

Generic 

Library  file 

.LST 

Generic 

List  file 

.MAP 

Generic 

Address  map  file 

.MOD 

Generic 

Module  file 

.MSG 

COBOL 

Message  file 

.MSP 

Windows 

Windows  Paint  file 

•OBJ 

Generic 

Relocatable  object  module 

.OVL 

Generic 

Overlay  file 

.OVR 

COBOL 

Compiler  overlay  file 

.PAS 

PASCAL 

PASCAL  language  source  code 

.PIF 

Windows 

Program  information  file 

.QLB 

Generic 

Library  file  for  Microsoft’s  Quick  products 

.RC 

Windows 

Resource  script  file 

.REF 

CREF 

Cross-reference  listing  file 

.RES 

Windows 

Compiled  resource  file 

.SCR 

Generic 

Script  file 

.SYM 

Generic 

Symbol  file 

.SYS 

Generic 

System  file  or  device  driver 

.TMP 

Generic 

Temporary  file 

.TRM 

Windows 

Terminal  file 

.TXT 

Generic 

Text  file  or  Windows  Notepad  file 

.WRI 

Windows 

Write  file 
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Appendix  K 

Segmented  (New)  .EXE  File  Header  Format 


Microsoft  Windows  requires  much  more  information  about  a  program  than  is  available  in 
the  format  of  the  .EXE  executable  file  supported  by  MS-DOS.  For  example,  Windows  needs 
to  identify  the  various  segments  of  a  program  as  code  Segments  or  data  segments,  to  iden¬ 
tify  exported  and  imported  functions,  and  to  store  the  program’s  resources  (such  as  icons, 
cursors,  menus,  and  dialog-box  templates).  Windows  must  also  support  dynamically  link¬ 
able  library  modules  containing  routines  that  programs  and  other  library  modules  can  call. 
For  this  reason,  Windows  programs  use  an  expanded  .EXE  header  format  called  the  New 
Executable  file  header  format.  This  format  is  used  for  Windows  programs,  Windows  li¬ 
brary  modules,  and  resource-only  files  such  as  the  Windows  font  resource  files. 


The  Old  Executable  Header 

The  New  Executable  file  header  format  incorporates  the  existing  MS-DOS  executable  file 
header  format.  In  fact,  the  beginning  of  a  New  Executable  file  is  simply  a  normal  MS-DOS 
.EXE  header.  The  4  bytes  at  offset  3CH  are  a  pointer  to  the  beginning  of  the  New  Execut¬ 
able  header.  (Offsets  are  from  the  beginning  of  the  Old  Executable  header.) 


Length 

Offset  (bytes)  Contents 

OOH  1  Signature  byte  M 

OlH  1  Signature  byte  Z 

3CH  4  Offset  of  New  Executable  header  from  beginning  of  file 

This  normal  MS-DOS  .EXE  header  can  contain  size  and  relocation  information  for  a  non- 
Windows  MS-DOS  program  that  is  contained  within  the  .EXE  file  along  with  the  Windows 
program.  This  program  is  run  when  the  .EXE  file  is  executed  from  the  MS-DOS  command 
line.  Most  Windows  programmers  use  a  standard  program  that  simply  prints  the  message 
This  program  requires  Microsoft  Windows. 
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The  New  Executable  Header 

The  beginning  of  the  New  Executable  file  header  contains  information  about  the  location 
and  size  of  various  tables  within  the  header.  (Offsets  are  from  the  beginning  of  the  New 
Executable  header.) 


Length 

Offset  (bytes) 


OOH  1 

OlH  1 

02H  1 

03H  1 

04H  2 

06H  2 

OSH  4 

OCH  2 

OEH  2 


lOH  2 

12H  2 

14H  2 

16H  2 

18H  2 


Contents 

Signature  byte  N 
Signature  byte  E 
LINK  version  number 
LINK  revision  number 

Offset  of  beginning  of  entry  table  relative  to  beginning 
of  New  Executable  header 
Length  of  entry  table 

32-bit  checksum  of  entire  contents  of  file,  using  zero 
for  these  4  bytes 
Module  flag  word  Csee  below) 

Segment  number  of  automatic  data  segment  (0  if 
neither  SINGLEDATA  nor  MULTIPLEDATA  flag  is  set 
in  flag  word) 

Initial  size  of  local  heap  to  be  added  to  automatic  data 
segment  (0  if  there  is  no  local  heap) 

Initial  size  of  stack  to  be  added  to  automatic  data  seg¬ 
ment  (0  for  library  modules) 

Initial  value  of  instruction  pointer  (IP)  register  on  entry 
to  program 

Initial  segment  number  for  setting  code  segment  (CS) 
register  on  entry  to  program 
Initial  value  of  stack  pointer  (SP)  register  on  entry  to 
program  (0  if  stack  segment  is  automatic  data  seg¬ 
ment;  stack  should  be  set  above  static  data  area  and 
below  local  heap  in  automatic  data  segment) 

(more) 
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Length 

Offset  (bytes)  Contents 


lAH  2 

ICH  2 

lEH  2 

20H  2 

22H  2 

24H  2 

26H  2 

28H  2 

2AH  2 

2CH  4 

30H  2 

32H  2 

34H  12 


Segment  number  for  setting  stack  segment  (SS)  register 
on  entry  to  program  (0  for  library  modules) 

Number  of  entries  in  segment  table 
Number  of  entries  in  module  reference  table 
Number  of  bytes  in  nonresident  names  table 
Offset  of  beginning  of  segment  table  relative  to  begin¬ 
ning  of  New  Executable  header 
Offset  of  beginning  of  resource  table  relative  to  begin¬ 
ning  of  New  Executable  header 
Offset  of  beginning  of  resident  names  table  relative  to 
beginning  of  New  Executable  header 
Offset  of  beginning  of  module  reference  table  relative 
to  beginning  of  New  Executable  header 
Offset  of  beginning  of  imported  names  table  relative  to 
beginning  of  New  Executable  header 
Offset  of  nonresident  names  table  relative  to  beginning 
of  file 

Number  of  movable  entry  points  listed  in  entry  table 
Alignment  shift  count  (0  is  equivalent  to  9) 

Reserved  for  expansion 


The  module  flag  word  at  offset  OCH  in  the  New  Executable  header  is  defined  as  shown  in 
Figure  K-1. 


1  if  SINGLEDATA  (library  module) 

0  if  NOAUTODATA  (library  module) 

I -  1  if  MULTIPLEDATA  (program  module) 


1  if  module  runs  in  real  mode 

•  1  if  module  runs  in  protected  mode 

•  1  if  module  is  nonconforming 

(valid  stack  is  not  maintained) 

1  if  library  module 
0  if  program  module 


Figure  K-1.  The  module flag  word. 
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The  segment  table 

This  table  contains  one  8-byte  record  for  every  code  and  data  segment  in  the  program  or 
library  module.  Each  segment  has  an  ordinal  number  associated  with  it.  For  example,  the 
first  segment  has  an  ordinal  number  of  1.  These  segment  numbers  are  used  to  reference 
the  segments  in  other  sections  of  the  New  Executable  file.  (Offsets  are  from  the  beginning 
of  the  record.) 


Length 

Offset  (bytes)  Contents 


OOH  2 

02H  2 

04H  2 

06H  2 


Offset  of  segment  relative  to  beginning  of  file  after 
shifting  value  left  by  alignment  shift  count 
Length  of  segment  (OOOOH  for  segment  of  65536  bytes) 
Segment  flag  word  (see  below) 

Minimum  allocation  size  for  segment;  that  is,  amount  of 
space  Windows  reserves  in  memory  for  segment 
(OOOOH  for  minimum  allocation  size  of  65536  bytes) 


The  segment  flag  word  is  defined  as  shown  in  Figure  K-2. 


F 

E 

D 

C 

B 

A 

9 

8 

7 

6 

5 

4 

3 

2 

• 

0 

^ : 

V— ^ 

ir 

1  if  DATA 
0  if  CODE 

1  if  segment  data  is  ITERATED 
1  if  segment  is  MOVABLE 
0  if  segment  is  FIXED 

1  if  segment  is  PURE  or  SHAREABLE 
0  if  segment  is  IMPURE  or  NONSHAREABLE 

1  if  segment  is  PRELOAD 
0  if  segment  is  LOADONCALL 

1  if  code  segment  and  EXECUTEONLY 
0  if  data  segment  and  READONLY 

1  if  segment  has  relocation  information 
1  if  segment  has  debugging  information 
Reserved  for  protected  mode 
descriptor  privilege  level 

Priority  level  for  discarding 


Figure  K-2.  The  segment  flag  word. 
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The  resource  table 

Resources  are  segments  that  contain  data  but  are  not  included  in  a  program’s  normal  data 
segments.  Resources  are  commonly  used  in  Windows  programs  to  store  menus,  dialog-box 
templates,  icons,  cursors,  and  text  strings,  but  they  can  also  be  used  for  any  type  of  read¬ 
only  data.  Each  resource  has  a  type  and  a  name,  both  of  which  can  be  represented  by 
either  a  number  or  an  ASCII  name. 

The  resource  table  begins  with  a  resource  shift  count  used  for  adjusting  other  values  in  the 
table.  (Offsets  are  from  the  beginning  of  the  table.) 


Length 

Offset 

(bytes) 

Contents 

OOH 

2 

Resource  shift  count 

This  is  followed  by  one  or  more  resource  groups,  each  defining  one  or  more  resources. 
(Offsets  are  from  the  beginning  of  the  group.) 

Length 

Offset 

(bytes) 

Contents 

OOH 

2 

Resource  type  (0  if  end  of  table) 

If  high  bit  set,  type  represented  by  predetermined 

number  (high  bit  not  shown): 

1  Cursor 

2  Bitmap 

3  Icon 

4  Menu  template 

5  Dialog-box  template 

6  String  table 

7  Font  directory 

8  Font 

9  Keyboard-accelerator  table 

If  high  bit  not  set,  type  is  ASCII  text  string  and  this 

value  is  offset  from  beginning  of  resource  table, 
pointing  to  1-byte  value  with  number  of  bytes  in 
string  followed  by  string  itself. 

02H 

2 

Number  of  resources  of  this  type 

04H 

4 

Reserved  for  run-time  use 

08H 

12  each 

Resource  description 

Each  resource  description  requires  12  bytes.  (Offsets  are  from  the  beginning  of  the 
description.) 
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Length 

Offset  (bytes)  Contents 


OOH  2 

02H  2 

04H  2 

06H  2 


OSH  4 


Offset  of  resource  relative  to  beginning  of  file  after 
shifting  left  by  resource  shift  count 

Length  of  resource  after  shifting  left  by  resource  shift 
count 

Resource  flag  word  (^see  below) 

Resource  name 

If  high  bit  set,  represented  by  a  number;  otherwise, 
type  is  ASCII  text  string  and  this  value  is  offset  from 
beginning  of  resource  table,  pointing  to  1-byte  value 
with  number  of  bytes  in  string  followed  by  string 
itself. 

Reserved  for  run-time  use 


The  resource  flag  word  is  defined  as  shown  in  Figure  K-3. 


F 

E 

D 

C 

B 

A 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 

- 

1  if  resource  is  MOVABLE 
0  if  resource  is  FIXED 

1  if  resource  is  PURE  or  SHAREABLE 
0  if  resource  is  IMPURE  or  NONSHAREABLE 

1  if  resource  is  PRELOAD 
0  if  resource  is  LOADONCALL 

Priority  level  for  discarding 


Figure  K-3.  The  resource  flag  word. 

The  resident  names  table 

This  table  contains  a  list  of  ASCII  strings.  The  first  string  is  the  module  name  given  in  the 
module  definition  file.  The  other  strings  are  the  names  of  all  exported  functions  listed  in 
the  module  definition  file  that  were  not  given  explicit  ordinal  numbers  or  that  were  ex¬ 
plicitly  specified  in  the  file  as  resident  names.  (Exported  functions  with  explicit  ordinal 
numbers  in  the  module  definition  file  are  listed  in  the  nonresident  names  table.) 

Each  string  is  prefaced  by  a  single  byte  indicating  the  number  of  characters  in  the  string 
and  is  followed  by  a  word  (2  bytes)  referencing  an  element  in  the  entry  table,  beginning  at 
1.  The  word  that  follows  the  module  name  is  0.  (Offsets  are  from  the  beginning  of  the 
record.) 
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Length 

Offset 

(bytes) 

Contents 

OOH 

1 

Number  of  bytes  in  string  (0  if  end  of  table) 

OlH 

n 

ASCII  string,  not  null-terminated 

w+1 

2 

Index  into  entry  table 

The  module  reference  table 

The  module  reference  table  contains  2  bytes  for  every  external  module  the  program  uses. 
These  2  bytes  are  an  offset  into  the  imported  names  table. 

The  imported  names  table 

The  imported  names  table  contains  a  list  of  ASCII  strings.  These  strings  are  the  names  of 
all  other  modules  that  are  referenced  through  imported  functions.  The  strings  are  prefaced 
with  a  single  byte  indicating  the  length  of  the  string. 

For  most  Windows  programs,  the  imported  names  table  includes  KERNEL,  USER,  and  GDI, 
but  it  can  also  include  names  of  other  modules,  such  as  KEYBOARD  and  SOUND.  (Offsets 
are  from  the  beginning  of  the  record.) 


Length 

Offset  (bytes)  Contents 

OOH  1  Number  of  bytes  in  name  string 

OlH  n  ASCII  name  string,  not  null-terminated 

These  strings  do  not  necessarily  start  at  the  beginning  of  the  imported  names  table;  the 
names  are  referenced  by  offsets  specified  in  the  module  reference  table. 

The  entry  table 

This  table  contains  one  member  for  every  entry  point  in  the  program  or  library  module. 
(Every  public  FAR  function  or  procedure  in  a  module  is  an  entry  point.)  The  members  in 
the  entry  table  have  ordinal  numbers  beginning  at  1.  These  ordinal  numbers  are  refer¬ 
enced  by  the  resident  names  table  and  the  nonresident  names  table. 

LINK  versions  4.0  and  later  bundle  the  members  of  the  entry  table.  Each  bundle  begins 
with  the  following  information.  (Offsets  are  from  the  beginning  of  the  bundle.) 


Length 

Offset  (bytes)  Contents 

OOH  1  Number  of  entry  points  in  bundle  (0  if  end  of  table) 

OlH  1  Segment  number  of  entry  points  if  entry  points  in  bun¬ 

dle  are  in  single  fixed  segment;  OFFH  if  entry  points 
in  bundle  are  in  movable  segments 
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For  a  bundle  containing  entry  points  in  fixed  segments,  each  entry  point  requires  3  bytes. 
(Offsets  are  from  the  beginning  of  the  entry  description.) 


Length 

Offset 

(bytes) 

Contents 

OOH 

1 

Entry-point  flag  byte  isee  below) 

OlH 

2 

Offset  of  entry  point  in  segment 

For  bundles  containing  entry  points  in  movable  segments,  each  entry  point  requires  6 

bytes.  (Offsets 

are  from  the  beginning  of  the  entry  description.) 

Length 

Offset 

(bytes) 

Contents 

OOH 

1 

Entry-point  flag  byte  (see  below) 

OlH 

2 

Interrupt  3FH  instruction:  CDH  3FH 

03H 

1 

Segment  number  of  entry  point 

04H 

2 

Offset  of  entry-point  segment 

The  entry-point  flag  byte  is  defined  as  shown  in  Figure  K-4. 


7 

6 

5 

4 

3 

2 

1 

0 

~T 

1 

1  if  entry  is  exported 
1  if  entry  uses  single  data 
(library  module) 

Number  of  parameter  words 


Figure  K-4.  The  entry-point  flag. 


The  nonresident  names  table 

This  table  contains  a  list  of  ASCII  strings.  The  first  string  is  the  module  description  from 
the  module  definition  file.  The  other  strings  are  the  names  of  all  exported  functions  listed 
in  the  module  definition  file  that  have  ordinal  numbers  associated  with  them.  (Exported 
functions  without  ordinal  numbers  in  the  module  definition  file  are  listed  in  the  resident 
names  table.) 

Each  string  is  prefaced  by  a  single  byte  indicating  the  number  of  characters  in  the  string 
and  is  followed  by  a  word  (2  bytes)  referencing  a  member  of  the  entry  table,  beginning  at 
1.  The  word  that  follows  the  module  description  string  is  0.  (Offsets  are  from  the  beginning 
of  the  table.) 
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Offset 

Length 

(bytes) 

Contents 

OOH 

1 

Number  of  bytes  in  string  (0  if  end  of  table) 

OlH 

n 

ASCII  string,  not  null-terminated 

w+1 

2 

Index  into  entry  table 

The  code  and  data  segment 

Following  the  various  tables  in  the  New  Executable  file  header  are  the  code  and  data  seg¬ 
ments  of  the  program  or  library  module. 

If  the  code  or  data  segment  is  flagged  in  the  segment  flag  word  as  ITERATED,  the  segment 
is  organized  as  follows.  (Offsets  are  from  the  beginning  of  the  segment.) 


Offset 

Length 

(bytes) 

Contents 

OOH 

2 

Number  of  iterations  of  data 

02H 

2 

Number  of  bytes  of  data 

04H 

n 

Data 

Otherwise,  the  size  of  the  segment  data  is  given  by  the  length  of  the  segment  field  in  the 
segment  table. 

If  the  segment  is  flagged  in  the  segment  flag  word  as  containing  relocation  information, 
then  the  relocation  table  begins  immediately  after  the  segment  data.  Windows  uses  the 
relocation  table  to  resolve  references  within  the  segments  to  functions  in  other  segments 
in  the  same  module  and  to  imported  functions  in  other  modules.  (Offsets  are  from  the 
beginning  of  the  table.) 


Length 

Offset  Obytes)  Contents 

OOH  2  Number  of  relocation  items 

Each  relocation  item  requires  8  bytes.  (Offsets  are  from  the  beginning  of  the  relocation 
item.) 


Length 

Offset  (bytes)  Contents 


OOH  1  Type  of  address  to  insert  in  segment: 

OlH  Offset  only 
02H  Segment  only 
03H  Segment  and  offset 


(more) 
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Offset 

Length 

(bytes) 

Contents 

OlH 

1 

Relocation  type: 

OOH  Internal  reference 

OlH  Imported  ordinal 

02H  Imported  name 

If  bit  2  set,  relocation  type  is  additive  isee  below) 

02H 

2 

Offset  of  relocation  item  within  segment 

The  next  4  bytes  depend 

on  the  relocation  type.  If  the  relocation  type  is  an  internal  refer- 

ence  to  a  segment  in  the  same  module,  these  bytes  are  defined  as  follows.  (Offsets  are 
from  the  beginning  of  the  relocation  item.) 

Offset 

Length 

(bytes) 

Contents 

04H 

1 

Segment  number  for  fixed  segment;  OFFH  for  movable 

segment 

05H 

1 

0 

06H 

2 

If  MOVABLE  segment,  ordinal  number  referenced  in 

entry  table;  if  FIXED  segment,  offset  into  segment 

If  the  relocation  type  is  an  imported  ordinal  to  another  module,  then  these  bytes  are 
defined  as  follows.  (Offsets  are  from  the  beginning  of  the  relocation  item.) 

Offset 

Length 

(bytes) 

Contents 

04H 

2 

Index  into  module  reference  table 

O6H 

2 

Function  ordinal  number 

Finally,  if  the  relocation  type  is  an  imported  name  of  a  function  in  another  module,  these 
bytes  are  defined  as  follows.  (Offsets  are  from  the  beginning  of  the  relocation  item.) 

Offset 

Length 

Obytes) 

Contents 

04H 

2 

Index  into  module  reference  table 

06H 

2 

Offset  within  imported  names  table  to  name  of  im- 

ported  function 
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If  the  ADDITIVE  flag  of  the  relocation  type  is  set,  the  address  of  the  external  function  is 
added  to  the  contents  of  the  address  in  the  target  segment.  If  the  ADDITIVE  flag  is  not  set, 
then  the  target  contains  an  offset  to  another  target  within  the  same  segment  that  requires 
the  same  relocation  address.  This  defines  a  chain  of  target  addresses  that  get  the  same  ad¬ 
dress.  The  chain  is  terminated  with  a  -1  entry. 


Charles  Petzold 
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Appendix  L 

Intel  Hexadecimal  Object  File  Format 


The  MCS-86  hexadecimal  object  file  format  provides  a  means  of  recording  a  program’s 
binary  (compiled  or  assembled)  image  in  a  text-only  (printable)  file  format.  This  format 
makes  it  easy  to  transfer  the  program  between  computers  over  telephone  lines  without 
using  special  communications  software.  More  important,  it  provides  a  ready  means  of 
transferring  programs  between  computers  and  the  various  types  of  laboratory  equipment 
typically  used  during  the  development  of  specialized  programs. 

The  MCS-86  hexadecimal  file  format  is  a  superset  of  Intel’s  older  Intellec-8  hexadecimal 
object  file  format.  Intel  originally  designed  the  Intellec-8  format  for  use  with  its  8-bit 
microprocessor  line.  The  format  rapidly  gained  acceptance  among  other  microprocessor 
manufacturers.  When  Intel  subsequently  developed  the  MCS-86  microprocessor  family,  it 
also  expanded  the  Intellec-8  hexadecimal  file  format  into  the  MCS-86  hexadecimal  file 
format  to  support  the  new  microprocessors’  extended  addressing  capabilities. 

The  MCS-86  hexadecimal  object  file  format  should  not  be  confused  with  the  object  (.OBJ) 
files  produced  by  the  Microsoft  Macro  Assembler  (MASM)  and  language  compilers.  The 
MCS-86  hexadecimal  object  file  format  is  referred  to  as  an  absolute  object  file  format 
because  the  code  contained  within  the  file  has  been  completely  linked  and  all  address  ref¬ 
erences  have  already  been  resolved.  The  object  modules  produced  by  the  assembler  and 
compilers  (.OBJ  files)  are  referred  to  as  relocatable  object  modules  because  they  contain 
the  information  necessary  to  relocate  the  enclosed  code  to  any  memory  address  for 
execution. 

The  MCS-86  hexadecimal  object  file  format  consists  of  four  types  of  ASCII  text  records: 

•  Data  record 

•  End-of-file  record 

•  Extended-address  record 

•  Start-address  record 

All  records  begin  with  a  record  mark  consisting  of  a  single  ASCII  colon  character  (:). 

The  remainder  of  the  record  consists  of  a  variable  number  of  ASCII  hexadecimal  digit 
pairs  (OO-OFH),  each  representing  an  unsigned  byte  value  (0-255  decimal).  The  first  digit 
represents  the  value  of  the  high  nibble  (bits  7-4)  of  the  byte;  the  second  digit  represents 
the  value  of  the  low  nibble  (bits  3-0).  These  digit  pairs  begin  immediately  after  the  record 
mark  and  continue  through  the  end  of  the  record  without  any  separation  between  them. 

All  records  have  the  following  fields,  in  the  order  listed: 

•  A  fixed-length  record  length  field 

•  A  fixed-length  address  field  (optional) 

•  A  fixed-length  record  type  field 
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•  A  fixed-length  or  variable-length  data  field 

•  A  fixed-length  checksum  field 

The  fixed-length  record  length  field  consists  of  the  first  digit  pair  following  the  record 
mark  and  gives  the  length  of  the  record-type-dependent  variable-length  data  field. 

The  optional  fixed-length  address  field  consists  of  the  second  and  third  digit  pairs  follow¬ 
ing  the  record  mark.  The  first  digit  pair  of  this  field  (second  digit  pair  of  the  record)  gives 
the  high  byte  of  a  word  address  value  (bits  15-8);  the  second  digit  pair  (third  digit  pair  of 
the  record)  gives  the  low  byte  of  a  word  address  value  (bits  7-0).  If  the  record  type  does 
not  use  the  address  field,  then  the  field  contains  a  fill-in  value  consisting  of  the  four- 
character  ASCII  string  0000. 

The  fixed-length  record  type  field  consists  of  the  fourth  digit  pair  of  the  record  and  indi¬ 
cates  the  type  of  data  the  record  contains.  The  valid  record-type  values  are 


Value  Type 

OOH  Data  record 

OlH  End-of-file  record 

02H  Extended-address  record 

03H  Start-address  record 

All  records  end  with  a  fixed-length  checksum  field.  This  field  contains  the  negative  of 
the  sum  of  all  byte  values  represented  by  the  digit  pairs  in  the  record,  from  the  record 
length  field  through  the  last  digit  pair  before  the  checksum  field.  The  checksum  field  is 
used  to  determine  whether  an  error  occurred  during  the  transmission  of  a  record  between 
computers  or  other  pieces  of  equipment. 

(The  receiving  equipment  can  easily  perform  this  error  checking  as  each  record  is 
received.  It  only  has  to  add  all  digit  pairs  of  the  record,  including  the  checksum,  and 
ignore  any  overflow  beyond  8  bits.  The  total  should  be  OOH,  because  the  checksum  is  the 
negative  of  the  summation  of  all  preceding  digit  pairs.) 

The  variable-length  data  field  of  the  data  record  contains  the  actual  data  bytes  of  the  pro¬ 
gram’s  image.  In  data  records,  the  record  length  field  indicates  the  number  of  bytes,  each 
represented  as  a  digit  pair,  contained  within  the  data  field;  the  address  field  gives  the  off¬ 
set  within  the  current  memory  segment  at  which  to  load  the  record’s  data  into  memory. 

The  fixed-length  data  field  of  the  extended-address  record  establishes  the  memory  seg¬ 
ment  into  which  subsequent  data  records  are  to  be  loaded.  In  extended-address  records, 
the  data  field  consists  of  a  single  field  identical  to  the  address  field.  The  address  field  of  an 
extended-address  record  always  contains  the  ASCII  0000  filler,  and  the  record  length  field 
always  contains  ASCII  02,  which  reflects  the  fixed  length  of  the  data  field.  The  memory 
segment  (also  known  as  the  memory  frame)  established  by  an  extended-address  record 
remains  in  effect  until  the  next  extended-address  record  is  encountered;  thus,  all  data 
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records  following  the  most  recent  extended-address  record  are  loaded  in  the  established 
memory  segment.  See  PROGRAMMING  IN  MS-DOS:  Programming  Tools:  The  Microsoft 
Object  Linker. 

Figures  L-1  and  L-2  show  how  the  extended-address  record  and  the  data  record  combine  to 
load  the  byte  values  OFDH,  0B9H,  75H,  31H,  OECH,  0A8H,  64H,  and  20H  into  memory  start¬ 
ing  at  address  9A6EH:429FH. 


checksum 

data  =  segment  address 

record  type  =  extended-address  record 

address  (filler) 

record  length 

record  mark 


Figure  L-1.  The  extended-address  record. 


1 

0  8 

n 

0  0 

- 1 - 1  1 - 1 

F  D  B  9  7  5  3  1 

_ 1 _ 1 _ 1 _ 1 

1 - \ - 1 - 1 - 

ECA86420 

1 _ 1 _ 1  1 

m 

checksum - 

' —  data 

-  record  type  =  data  record 

-  address 

-  record  length 

-  record  mark 


Figure  L-2.  The  data  record. 

The  start-address  record  provides  the  CS  and  IP  register  values  at  which  program  execu¬ 
tion  begins.  This  record  contains  the  register  values  within  the  fixed-length  data  field.  The 
address  field  of  a  start-address  record  always  contains  the  ASCII  0000  filler,  and  the  record 
length  field  always  contains  ASCII  04,  which  reflects  the  fixed  length  of  the  data  field.  The 
example  in  Figure  L-3  shows  a  CS:IP  setting  (program  entry  point)  of  F924H:E69AH. 

The  end-of-file  record  marks  the  end  of  an  MCS-86  hexadecimal  file.  Under  the  MCS-86 
hexadecimal  file  definition,  the  end-of-file  record  does  not  contain  any  variable-value 
fields;  the  record  always  appears  as  shown  in  Figure  L-4. 
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checksum 
data: 

IP 
CS 

record  type  =  start-address  record 
address  (filler) 
record  length 
record  mark 

Figure  L-3.  The  start-address  record. 


checksum 

record  type  =  end-of-file  record 
address  (filler) 
record  length 
record  mark 

Figure  L-4.  The  end-of-file  record. 

Traditionally,  development  equipment  and  programs  that  accept  the  MCS-86  hexadecimal 
file  format  as  input  also  recognize  an  alternate  end-of-file  record.  The  alternate  record  con¬ 
sists  of  a  data  record  that  contains  no  data;  therefore,  its  record  length  field  contains  00. 
Figure  L-5  shows  this  alternate  end-of-file  record. 

DEBUG  is  the  only  program  supplied  with  MS-DOS  that  accepts  the  MCS-86  hexadecimal 
file  format.  Even  then,  DEBUG  only  loads  hexadecimal  files  into  memory;  it  does  not  save 
a  program  back  to  disk  as  a  hexadecimal  file.  (The  same  applies  for  SYMDEB  and  for 
CodeView.) 


checksum 

record  type  =  data  record 
address  (filler) 
record  length 
record  mark 

Figure  L-5.  The  alternate  end-of-file  record. 
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While  loading  a  hexadecimal  file,  DEBUG  actually  processes  only  data  records  and  end-of- 
file  records;  it  ignores  both  start-address  records  and  any  extended-address  records.  Thus, 
DEBUG  actually  supports  only  the  older  Intellec-8  hexadecimal  file  format  but  will  not 
reject  the  file  if  it  also  contains  the  newer  MCS-86  hexadecimal  file  records. 

DEBUG  does  not  support  MCS-86  records  because  it  must  operate  within  the  MS-DOS 
environment  and  MS-DOS  does  not  support  the  loading  of  programs  into  absolute  memory 
locations — a  restriction  imposed  by  most  general-purpose  operating  systems.  Because 
DEBUG  cannot  load  the  data  records  into  the  absolute  segments  indicated  by  the 
extended-address  records,  it  simply  loads  the  program  image  contained  within  the  data 
records  in  a  manner  similar  to  that  in  which  a  .COM  program  is  loaded.  See  PROGRAM¬ 
MING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  for  ms-dos:  Structure  of  an  Appli¬ 
cation  Program.  DEBUG  uses  the  address  field  for  the  data  records  as  the  offset  into  the 
.COM  program  segment  at  which  to  load  the  contents  of  the  records. 

The  sample  QuickBASIC  (versions  3.0  and  later)  program  shown  in  Figure  L-6  converts 
binary  files,  including  .COM  files,  into  limited  MCS-86  hexadecimal  files  that  DEBUG  can 
load.  Examining  this  program  can  provide  additional  understanding  of  the  structure  of 
Intel  hexadecimal  files. 

'Binary-to-Hex  file  conversion  utility. 

'Requires  Microsoft  QuickBASIC  version  3.0  or  later. 


DEFINT  A-Z 

CONST  FALSE  =  0 
CONST  TRUE  =  NOT  FALSE 

DEF  FNHXB$(X)  =  RIGHT$ (HEX$ (&H1 00  +  X) ,  2) 
DEF  FNHXW$(X!)  =  RIGHT$("000"  +  HEX$(X!), 
DEF  FNM0D(X,  Y)  =  X!  -  INT(X!/Y)  ♦  Y 

CONST  SRCCNL  =  1 
CONST  TGTCNL  =  2 


'  All  variables  are  integers 

*  unless  otherwise  declared. 

'  Value  of  logical  FALSE. 

'  Value  of  logical  TRUE. 

*  Return  2-digit  hex  value  for  X. 

4)  '  Return  4-digit  hex  value  for  X! 

'  X!  MOD  Y  (the  MOD  operation  is 
'  only  for  integers) . 

'  Source  (.BIN)  file  channel. 

*  Target  (.HEX)  file  channel. 


LINE  INPUT  "Enter  full  name  of  source  .BIN  file  :  ";SRCFIL$ 

OPEN  SCRCFIL$  FOR  INPUT  AS  SRCCNL  '  Test  for  source  (.BIN)  file. 

SRCSIZ!  =  LOF (SRCCNL)  *  Save  file's  size. 

CLOSE  SRCCNL 

IF  (SRCSIZ!  >  65536)  THEN  '  Reject  if  file  exceeds  64  KB. 

PRINT  "Cannot  convert  file  larger  than  64  KB." 

END 

END  IF 


LINE  INPUT  "Enter  full  name  of  target  .HEX  file  :  ";TGTFIL$ 

OPEN  TGTFIL$  FOR  OUTPUT  AS  TGTCNL  '  Test  target  (.HEX)  filename. 

CLOSE  TGTCNL 

Figure  L-6.  QuickBASIC  binary-to-hexadecimal file  conversion  utility.  (more) 
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DO 

LINE  INPUT  "Enter  starting  address 
ADRBGN!  =  VAL("&H"  +  L$) 

IF  (ADRBGN!  <  0)  THEN 
ADRBGN!  =  65536  +  ADRBGN! 

END  IF 

ADREND!  =  ADRBGN!  +  SRCSIZ!  -  1 
IF  (ADREND!  >  65535)  THEN 
PRINT  "Entered  start  address  causes 
END  IF 

LOOP  UNTIL  (ADRFLD!  >=  0)  AND  (ADRFLD !  <= 


:  .BIN  file  in  HEX  :  ";L$ 

'  Convert  ASCII  HEX  address  value 
'  to  binary  value. 

'  HEX  values  8000-FFFFH  convert 
'  to  negative  values. 

'  Calculate  resulting  end  address. 
'  Reject  if  address  exceeds  FFFFH. 
end  address  to  exceed  FFFFH." 

=  65535)  AND  (ADREND!  <=  65535) 


DO 

LINE  INPUT  "Enter  byte  count  for  < 
SRCRLN  =  VAL("&H"  +  L$) 

IF  (SRCRLN  <  0)  THEN 
SRCRLN  =  65536  +  SRCRLN 
END  IF 

LOOP  UNTIL  (SRCRLN  >  0)  AND  (SRCRLN  < 

OPEN  SRCFIL$  AS  SRCCNL  LEN  =  SRCRLN 
FIELD#SRCCNL, SRCRLN  AS  SRCBLK$ 

OPEN  TGTFIL$  FOR  OUTPUT  AS  TGTCNL 
SRCREC  =  0 


record  in  HEX  :  ";L$ 

'  Convert  ASCII  HEX  max  record 
'  length  value  to  binary  value. 

'  HEX  values  8000-FFFFH  convert 
'  to  negative  values. 

'  Ask  again  if  not  1-255. 

'  Reopen  source  for  block  I/O. 

'  Reopen  target  for  text  output. 

'  Starting  source  block  #  minus  1  . 


FOR  ADRFLD!  =  ADRBGN!  TO  ADREND!  STEP  SRCRLN 
SRCREC  =  SRCREC  +  1 
GET  SRCCNL, SRCREC 

IF  (ADRFLD!  +  SRCRLN  >  ADREND!)  THEN 
BLK$=LEFT$ (SRCBLK$, ADREND ! -ADRFLD ! +1 ) 
ELSE 

BLK$  =  SRCBLK$ 

END  IF 


’  Convert  one  block  per  loop. 

’  Next  source  block. 

*  Read  the  source  block. 

'  If  last  block  less  than  full 
'  size:  trim  it. 

'  Else: 

'  Use  full  block. 


PRINT#TGTCNL, 

PRINT#TGTCNL,  FNHXB$ (LEN (BLK$) ) ; 
CHKSUM  =  LEN(BLK$) 

PRINT#TGTCNL, FNHXW$ (ADRFLD ! ) ; 


'  Write  record  mark. 

'  Write  data  field  size. 

'  Initialize  checksum  accumulate 
’  with  first  value. 

'  Write  record's  load  address. 


'  The  following  "AND  &HFF"  operations  limit  CHKSUM  to  a  byte  value. 

CHKSUM  =  CHKSUM  +  INT (ADRFLD ! /256)  AND  &HFF  ’  Add  hi  byte  of  adrs  to  csum. 
CHKSUM  =  CHKSUM  +  FNMOD (ADRFLD !, 256)  AND  &HFF  '  Add  lo  byte  of  adrs  to  csum. 


PRINT#TGTCNL,FNHXB$ (0) ; 


'  Write  record  type. 


Figure  L-6.  Continued. 


(more) 
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'  Don't  bother  to  add  record  type  byte  to  checksum  since  it's  0. 

FOR  IDX  =  1  TO  LEN(BLK$)  '  Write  all  bytes. 

PRINT#TGTCNL,FNHXB$(ASC(MID${BLK$,IDX, 1)));  ’  Write  next  byte. 

CHKSUM  =  CHKSUM  +  ASC (MID$ (BLK$, IDX, 1 ) )  AND  &HFF  '  Incl  byte  in  csum. 
NEXT  IDX 


CHKSUM  =  0  -  CHKSUM  AND  &HFF 
PRINT  #TGTCNL,FNHXB$ (CHKSUM) 
NEXT  ADRFLD! 

PRINT#TGTCNL,  0000000 1 FF" 

CLOSE  TGTCNL 
CLOSE  SRCCNL 

END 

Figure  L-6.  Continued. 


'  Negate  checksum  then  limit 
*  to  byte  value. 

'  End  record  with  checksum. 


'  Write  end-of-file  record. 

*  Close  target  file. 

*  Close  source  file. 


Keith  Burgoyne 
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8086/8088  Software  Compatibility  Issues 


In  general,  the  Intel  80286  microprocessor  running  in  real  mode  executes  8086/8088  soft¬ 
ware  correctly.  The  following  is  a  list  of  the  actions  to  take  to  compensate  for  the  minor 

differences  between  the  8086/8088  and  real  mode  of  the  80286. 

•  Bo  not  rely  on  8086/8088  instruction  clock  counts.  The  80286  takes  fewer  clocks 
for  most  instructions  than  the  8086/8088.  The  areas  to  look  into  are  delays  between 
I/O  operations  and  assumed  delays  when  the  8086/8088  is  operating  in  parallel 
with  an  8087  coprocessor. 

•  Note  that  divide  exceptions  point  to  the  DIV  instruction.  Any  interrupt  on  the  80286 
always  leaves  the  saved  CS:IP  value  pointing  to  the  instruction  that  failed.  On  the 
8086/8088,  the  CS:IP  value  saved  for  a  divide  exception  points  to  the  next  instruction. 

•  Set  up  numeric  exception  handlers  to  allow  prefixes.  The  saved  CS:IP  value  in  the 
NPX  environment  save  area  points  to  any  ESC  instruction  prefixes.  On  8086/8088 
systems,  this  value  points  only  to  the  ESC  instruction. 

•  Do  not  attempt  undefined  8086/8088  operations.  8086/8088  instructions  like  POP  CS 
or  MOV  CS,op  either  invoke  exception  06H  (Invalid  Opcode)  or  perform  a  protection 
setup  operation  like  LIDT  on  the  80286.  Undefined  bit  encodings  for  bits  5-3  of  the 
second  byte  of  POP  MEM  or  PUSH  MEM  invoke  exception  13H  on  the  80286. 

•  Do  not  rely  on  the  value  written  by  PUSH  SP.  The  80286  pushes  a  different  value  on 
the  stack  for  PUSH  SP  than  does  the  8086/8088.  If  the  value  pushed  is  important, 
replace  PUSH  SP  instructions  with  the  following  instructions: 

PUSH  BP 

MOV  BP,SP 

XCHG  BP, [BP] 

This  code  functions  like  the  8086/8088  PUSH  SP  instruction  on  the  80286. 

•  Do  not  shift  or  rotate  by  more  than  31  bits.  The  80286  masks  all  SHIFT/ROTATE 
counts  to  the  low  5  bits.  This  MOD  32  operation  limits  the  count  to  a  maximum  of  31 
bits.  With  this  change,  the  longest  SHIFT/ROTATE  instruction  is  39  clocks.  Without 
this  change,  the  longest  SHIFT/ROTATE  instruction  is  264  clocks,  which  delays 
interrupt  response  until  the  instruction  completes  execution. 

•  Do  not  duplicate  prefixes.  The  80286  sets  an  instruction-length  limit  of  10  bytes.  The 
only  way  to  exceed  this  limit  is  to  include  the  same  prefix  two  or  more  times  before 
an  instruction.  Exception  06H  occurs  if  the  instruction-length  limit  is  violated.  The 
8086/8088  has  no  instruction-length  limit. 

•  Do  not  rely  on  odd  8086/8088 LOCK  characteristics.  The  LOCK  prefix  and  its  corre¬ 
sponding  output  signal  should  be  used  only  to  prevent  other  bus  masters  from  inter¬ 
rupting  a  data  movement  operation.  The  80286  always  asserts  LOCK  during  an  XCHG 
instruction  with  memory  (even  if  the  LOCK  prefix  was  not  used).  LOCK  should  be 
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used  only  with  the  XCHG,  MOV,  MOVS,  INS,  and  OUTS  instructions.  The  80286 
LOCK  signal  will  not  go  active  during  an  instruction  prefetch. 

•  Do  not  rely  on  IDIV exceptions  for  quotients  of  80H  or 8000H.  The  80286  can  gener¬ 
ate  the  largest  negative  number  as  a  quotient  for  IDIV  instructions.  The  8086/8088 
generates  exception  OOH  (Divide  by  Zero)  instead. 

•  Do  not  rely  on  address  space  wraparound. 

•  Do  not  use  I/O  ports  0F8—0FFH.  These  are  reserved  for  controlling  the  80287  and 
future  microprocessor  extensions. 
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An  Object  Module  Dump  Utility 


The  program  OBJDUMP.C  displays  the  contents  of  an  object  file  as  individual  object 
records.  It  can  be  used  to  study  the  structure  of  object  modules  as  well  as  to  verify  the 
output  of  a  language  translator.  The  program  recognizes  all  of  the  object  record  types 
discussed  in  PROGRAMMING  IN  THE  MS-DOS  ENVIRONMENT:  Programming  Tools: 
Object  Modules. 

OBJDUMP.C  should  be  executed  with  the  following  syntax: 

OBJDUMP  filename 

where  filename  is  a  complete  filename  specification.  For  example,  to  dump  the  contents 
of  the  object  file  MYPROG.OBJ,  the  user  would  type 

OOBJDUMP  MYPROG.OBJ  <Enter> 

The  following  is  a  typical  object  record  as  displayed  by  OBJDUMP: 

Record  9:  96h  LNAMES 

96  002Eh  00  06  44  47  52  4F  55  50  05  5F  54  45  58  54  04  43 

4F  44  45  05  5F  44  41  54  41  04  44  41  54  41  05  43 

4F  4E  53  54  04  5F  42  53  53  03  42  53  53  3F 

This  sample  LNAMES  record  defines  a  null  name  and  eight  names  used  in  subsequent 

SEGDEF  and  GRPDEF  records.  The  first  3  bytes  of  the  record  (the  identifying  byte  and  the 
2-byte  record  length)  are  displayed  to  the  left  of  the  hexadecimal  and  ASCII  listings  of 
the  contents  of  the  record. 


*  ♦ 

*  OBJDUMP.C  —  display  contents  of  an  object  file  ♦ 

*  * 

*  ♦ 

*  Compile:  msc  objdump;  (Microsoft  C  version  4.0  or  later)  * 

*  Link:  link  objdump;  * 

*  Execute:  objdump  <filename>  * 

*  ♦ 


. .DGROUP.-TEXT.C 
ODE . -DATA . DATA . C 
ONST._BSS.BSS? 


#include  <fcntl.h> 

#define  TRUE  1 

#define  FALSE  *  0 


(more) 
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main (  argc,  argv  ) 
int  argc; 

char  **argv; 

{ 

unsigned  char  CurrentByte; 

int  Ob jFileHandle; 

int  CurrentLineLength;  /*  length  of  output  line  */ 

int  Ob jRecordNumber  =  0; 

int  Ob jRecordLength; 

int  Ob jRecordOf fset  =0;  /*  offset  into  current  object  record  */ 

char  ASCIIEquiv [1 7] ; 

char  Formatstring [24 ] ; 

char  *Ob jRecordName 0 ; 

char  *memset(); 


/*  open  the  object  file  */ 

Ob jFileHandle  =  open (  argv [1 ] , 0_BINARY  ); 

if(  Ob jFileHandle  ==  -1  ) 

{ 

printf(  "XnCan't  open  object  file\n''  ); 
exit  (  1  ) ; 

} 

/*  process  the  object  file  character  by  character  */ 

while  (  read(  Ob jFileHandle,  &CurrentByte,  1  )  ) 

{ 

switch (  Ob jRecordOffset  )  /*  action  depends  on  offset  into  record  ♦/ 

{ 

case(O):  /*  start  of  object  record  */ 

printf (  "\n\nRecord  %d:  %02Xh  %s", 

++Ob jRecordNumber,  CurrentByte,  Ob jRecordName (CurrentByte)  ); 
printf (  "\n%02X  ",  CurrentByte  ); 

++Ob jRecordOf fset; 
break; 

case(l):  /*  first  byte  of  length  field  */ 

Ob jRecordLength  =  CurrentByte; 

++Ob jRecordOf fset; 
break; 

case (2):  /*  second  byte  of  length  field  */ 

Ob jRecordLength  +=  CurrentByte  «  8;  /*  compute  record  length  */ 
printf  (  ”%04Xh  ”,  Ob jRecordLength  );  /*  show  length  */ 

CurrentLineLength  =  0; 

memset (  ASCIIEquiv,  *\0'  ,  17  );  /*  zero  this  string  */ 

++Ob jRecordOf fset; 

break; 


(more) 
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default:  /*  remaining  bytes  in  object  record  */ 

printf(  ”%02X  ",  CurrentByte  );  /♦  hex  */ 

if {  CurrentByte  <  0x20  I!  CurrentByte  >  0x7F  )  /*  ASCII  */ 

CurrentByte  =  ' . ' ; 

ASCIIEquiv [CurrentLineLength++]  =  CurrentByte; 

if (  CurrentLineLength  ==  1 6  I  I  /*  if  end  of  output  line  ...  */ 
Ob jRecordOffset  ==  Ob jRecordLength+2  ) 

{  /*  . . .  display  it  */ 

sprintf(  Formatstring,  "%%%ds%%s\n  ”, 

3*  (1 6-CurrentLineLength) +2  ); 
printf(  Formatstring,  "  ”,  ASCIIEquiv  ); 
memset (  ASCIIEquiv,  '\0*,  17  ); 

CurrentLineLength  =  0; 


if (  ++ob jRecordOffset  ==  Ob jRecordLength+3  )  /*  if  done  ...  */ 

Ob jRecordOffset  =0;  /*  . . .  process  another  record  */ 

break; 

} 

} 

if (  CurrentLineLength  )  /*  display  remainder  of  last  output  line  */ 

printf(  ”  %s”,  ASCIIEquiv  ); 

close  (  ObjFileHandle  ); 

printf(  ”\n%d  object  records\n”,  Ob jRecordNumber  ); 
return (  0  ) ; 


char  *ob jRecordName (  n  )  /*  return  object  record  name  */ 

int  n;  /*  n  =  record  type  ♦/ 

{ 

int  i; 

static  struct 

{ 

int  RecordNumber; 

char  *RecordName; 

}  RecordStruct [ ]  = 

{ 

0x80, "THEADR”, 

Ox88,”COMENT”, 

0x8A, "MODEND”, 

0x8C, "EXTDEF”, 

0x8E, "TYPDEF”, 

0x90,”PUBDEF”, 


(more) 
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0x94,"LINNUM", 
0x96,"LNAMES'', 
0x98,”SEGDEF”, 
0x9A,  *^GRPDEF", 
0x9C,”FIXUPP’', 
OxAO,"LEDATA", 
0xA2,"LIDATA", 
OxBO,"COMDEF", 
0x00, "******” 
}; 


int  RecordTableSize  =  sizeof (RecordStruct) /sizeof (RecordStruct [0] ) ; 


f or (  i=0;  i<RecordTableSize-1 ;  i++  )  /*  scan  table  for  name  */ 

if  {  RecordStruct [i] .RecordNumber  ==  n  ) 
break; 

return (  RecordStruct [i] .RecordName  ) ; 


Richard  Wilton 
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Appendix  O 

IBM  PC  ROM  BIOS  Calls 


To  invoke  an  IBM  PC  BIOS  routine,  set  register  AH  to  the  desired  function  and  execute  the 
software  interrupt  (INT)  for  the  desired  routine. 

Graphics  pixel  coordinates  and  cursor  row  and  column  coordinates  are  always  zero  based. 


Interrupt  lOH:  Video  Services 

Function  OOH:  Set  Video  Mode 

To  call: 

AH  =  OOH 

AL  =  mode: 


OOH 

l6-shade  gray  text 

EGA:  64-color 

40  by  25 

B000:8000H 

OlH 

l6/8-color  text 

EGA:  64-color 

40  by  25 

B000:8000H 

02H 

l6-shade  gray  text 

EGA:  64-color 

80  by  25 

B000:8000H 

03H 

l6/8-color  text 

EGA:  64-color 

80  by  25 

B000:8000H 

04H 

4-color  graphics 

320  by  200 

B000:8000H 

05H 

4-shade  gray  graphics 

320  by  200 

B000:8000H 

06H 

2-shade  gray  graphics 

640  by  200 

B000:8000H 

07H 

monochrome  text 

80  by  25 

B000:0000H 

OSH 

l6-color  graphics 

l60  by  200 

B000:0000H 

09H 

l6-color  graphics 

320  by  200 

B000:0000H 

OAH 

4-color  graphics 

640  by  200 

B000:0000H 

OBH 

Reserved 

OCH 

Reserved 

ODH 

l6-color  graphics 

320  by  200 

A000:0000H 

OEH 

l6-color  graphics 

640  by  200 

A000:0000H 

OFH 

monochrome  graphics 

640  by  350 

A000:0000H 

lOH 

l6/64-color  graphics 

640  by  350 

A000:0000H 

Returns: 

Nothing 
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Function  OlH:  Set  Cursor  Size  and  Shape 

To  call: 

AH  =  OlH 

CH  =  starting  scan  line 

CL  =  ending  scan  line 

Note:  CH  <  CL  gives  normal  one-part  cursor;  CH  >  CL  gives  two-part  cursor;  CH  =  20H 
gives  no  cursor. 

Returns: 

Nothing 

Function  02H:  Set  Cursor  Position 

To  call: 

AH  =  02H 

BH  =  display  page  (0  in  graphics) 

DH  =  row  number 

DL  =  line  number 

Returns: 

Nothing 

Function  03H:  Read  Cursor  Position,  Size,  and  Shape 

To  call: 

AH  =  03H 

BH  =  display  page 

Returns: 

CH  =  starting  scan  line 

CL  =  ending  scan  line 

DH  =  row  number 

DL  =  column  number 

Function  04H:  Read  light-Pen  Position 

To  calk 

AH  =  04H 
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Returns: 


AH 

=  status: 

OlH  pen  triggered 

OOH  not  triggered 

BX 

=  pixel  column  number 

CH 

=  pixel  line  number 

CX 

=  pixel  line  number  for  some  EGA  modes 

DH 

=  character  row  number 

DL 

=  character  column  number 

Function  05H:  Select  Active  Page 

To  call: 

AH  =  05H 

AL  =  page  number: 

00-07H  40-column  text  modes 

00 - 03H  80-column  text  modes 

varies  EGA  graphics  modes 

Note:  Each  page  =  2  KB  in  40-column  text  mode,  4  KB  in  80-column  text  mode. 

Returns: 

Nothing 

Function  06H:  Scroll  Window  Up 
Function  07H:  Scroll  Window  Down 

To  call: 

AH  =  06H  scroll  up 

=  07H  scroll  down 

AL  =  number  of  lines  to  scroll  (OOH  blanks  screen) 

BH  =  display  attributes  for  blank  lines 

CH  =  row  number  of  upper  left  corner 

CL  =  column  number  of  upper  left  corner 

DH  =  row  number  of  lower  right  corner 

DL  =  column  number  of  lower  right  corner 

Returns: 

Nothing 

Function  OSH:  Read  Character  and  Attribute  at  Cursor 

To  call: 

AH  =  08H 

BH  =  display  page  (for  text  mode  only) 
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Returns: 

If  text  mode: 

AH  =  color  attributes  of  character 

AL  =  ASCII  character  from  current  location 

If  graphics  mode: 

AL  =  ASCII  character  (OOH  if  unmatched) 

Function  09H:  Write  Character  and  Attribute 

To  call: 

AH  =  09H 

AL  =  ASCII  character  to  write 

BH  =  display  page 

BL  =  text  attribute  or  graphics  foreground  color 

CX  =  number  of  times  to  write  character  (must  be  >  0) 

Returns: 

Nothing 

Note:  Cursor  position  unchanged. 

Function  OAH:  Write  Character  Only 

To  call: 

AH  =  OAH 

AL  =  ASCII  character  to  write 

BH  =  display  page 

BL  =  graphics  foreground  color  (unused  in  text  modes) 

CX  =  number  of  times  to  write  character  (must  be  >  0) 

Returns: 

Nothing 

Note:  Cursor  position  unchanged. 

Function  OBH:  Select  Color  Palette 

To  call: 


AH 

=  0BH 

BH 

=  palette  color  ID 

BL 

=  color  or  palette  value 

Returns: 

Nothing 
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Function  OCH:  Write  Pixel  Dot 

To  call: 

AH  =  OCH 

AL  =  color  attribute  of  pixel 

CX  =  pixel  column  number 

DX  =  pixel  raster  line  number 

Returns: 

Nothing 

Function  ODH:  Read  Pixel  Dot 

Tocall: 

AH  =  ODH 

CX  =  pixel  column  number  (0-based) 

DX  =  pixel  raster  line  number  (0-based) 

Returns: 

AL  =  pixel  color  attribute 

Function  OEH:  Write  Character  as  TTY 

Tocall: 

AH  =  OEH 

AL  =  Ascii  character 

BH  =  display  page 

BL  =  foreground  color  of  character  (unused  in  text  mode) 

Returns: 

Nothing 

Note:  Cursor  position  advanced;  beep,  backspace,  linefeed,  and  carriage  return  active;  all 
other  characters  displayed. 

Function  OFH:  Get  Current  Video  Mode 

Tocall: 

AH  =  OFH 

Returns: 

AH  =  characters  per  line  (20, 40,  or  80) 

AL  =  current  video  mode  (^see  Interrupt  lOH  Function  OOH) 

BH  =  active  display  page 
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Function  13H:  Write  Character  String 

To  call: 

AH  =  13H 

AL  =  subfunction  number: 

OOH  string  shares  attribute  in  BL,  cursor  unchanged 
OlH  string  shares  attribute  in  BL,  cursor  advanced 
02H  each  character  has  attribute,  cursor  unchanged 
03H  each  character  has  attribute,  cursor  advanced 


BH 

=  active  display  page 

BL 

=  string  attribute  (for  AL  =  OOH  or  OlH  only) 

CX 

=  length  of  character  string 

DH 

=  starting  row  number 

DL 

=  starting  column  number 

ES:BP 

=  address  of  string  to  be  displayed 

Note:  For  AL  =  OOH  or  OlH,  string  =  ichar,  char,  char,  . . . ).  For  AL  =  02H  or  03H,  string  = 
ichar,  attr,  char,  attr,  . .  .)• 

Returns: 

Nothing 

Note:  For  AL  =  OlH  or  03H,  cursor  position  set  to  location  following  last  character  output. 


Interrupt  IIH:  Get  Peripheral  Equipment  List 


Returns: 

AX  =  equipment  list  code  word  (bit  settings  PPMURRRUFFVVUUCI): 

PP  number  of  printers  installed 

M  1  if  internal  modem  installed 

RRR  number  of  RS-232  ports  installed 

U  unused 

FF  number  of  floppy-disk  drives  minus  1  (0  =  one  drive) 

W  initial  video  mode: 

00  =  reserved 
01  =  40-by-25  color 

10  =  80-by-25  color 

11  =  80-by-25  monochrome 

U  unused 

C  1  if  math  coprocessor  installed 

I  1  if  IPL  (Initial  Program  Load)  diskette  installed 
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Interrupt  12H:  Get  Usable  Memory  Size  (KB) 

Returns: 

AX  =  available  memory  size  in  KB 


Interrupt  13H:  Disk  Services 

Function  OOH:  Reset  Disk  System 

TocalL 


AH  =  OOH 

AL  =  drive  number: 


00-7FH 

floppy  disk 

80-FFH 

fixed  disk 

Returns: 

CF 

=  0 

no  error 

1 

error 

AH 

=  error  code  (.see  Interrupt  13H  Function  OlH) 

Function  OlH:  Get  Disk  Status 

To  call: 

AH 

=  01H 

Returns: 

AH 

=  00H 

AL 

=  disk  status  of  previous  disk  operation: 

OOH 

no  error 

OlH 

invalid  command 

02H 

address  mark  not  found 

03H 

write  attempt  on  write-protected  disk  (F) 

04H 

sector  not  found 

05H 

reset  failed  (H) 

06H 

floppy  disk  removed  (F) 

07H 

bad  parameter  table  (H) 

OSH 

DMA  overflow  (F) 

09H 

DMA  crossed  64  KB  boundary 

OAH 

bad  sector  flag  (H) 

lOH 

uncorrectable  CRC  or  ECC  data  error 

IIH 

ECC  corrected  data  error  (H) 

20H 

controller  failed 

(more) 
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40H  seek  failed 

80H  time  out 

AAH  drive  not  ready  (H) 

BBH  undefined  error  (H) 

CCH  write  fault  (H) 

EOH  status  error  (H) 

Note:  H  =  fixed  disk  only,  F  =  floppy  disk  only. 

Function  02H:  Read  Disk  Sectors 
Function  03H:  Write  Disk  Sectors 
Function  04H:  Verify  Disk  Sectors 
Function  05H:  Format  Disk  Tracks 

TocalL 


AH 

=  02H  read  disk  sectors 

03H  write  disk  sectors 

04H  verify  disk  sectors 

05H  format  disk  track 

AL 

=  number  of  sectors 

CH 

=  cylinder  number 

CL 

=  sector  number  (unused  if  AH  =  05H) 

DH 

=  head  number 

DL 

=  drive  number 

ES:BX 

=  buffer  address  (unused  if  AH  =  04H) 

Returns: 

CF 

=  0  no  error 

1  error 

AH 

=  error  code  isee  Interrupt  13H  Function  OlH) 

IfAHwas05Honcall: 

ES:BX 

=  4-byte  address  field  entries,  1  per  sector: 
byte  0  cylinder  number 

byte  1  head  number 

byte  2  sector  number 

byte  3  sector-size  code: 

OOH  128  bytes  per  sector 

OlH  256  bytes  per  sector 

02H  512  bytes  per  sector  (standard) 

03H  1024  bytes  per  sector 

Function  OSH; 

:  Get  Current  Drive  Parameters 

To  call: 

AH 

=  08H 

DL 

=  drive  number 
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Returns: 

AX  =  OOH 

BH  =  OOH 

BL  =  drive  type 

CH  =  low-order  8  bits  of  10-bit  maximum  number  of  cylinders 

CL  =  bits  7  and  6  high-order  2  bits  of  10-bit  maximum  number  of  cylinders 

bits  5-0  maximum  number  of  sectors/track 
DH  =  maximum  head  number 

DL  =  number  of  drives  installed 

ES:DI  =  address  of  floppy-disk-drive  parameter  table 

Function  09H:  Initialize  Hard-Disk  Parameter  Table 

To  call: 

AH  =  09H 

Returns: 

Nothing 

Function  OAH:  Read  Long 

Reads  512-byte  sector  plus  4-byte  ECC  code. 

To  call: 

See  Interrupt  13H  Function  02H. 

Returns: 

See  Interrupt  13H  Function  02H. 

Function  OBH:  Write  Long 

Writes  512-byte  sector  plus  4-byte  ECC  code. 

To  call: 

See  Interrupt  13H  Function  03H. 

Returns: 

See  Interrupt  13H  Function  03H. 

Function  OCH:  Seek  to  Head 

Positions  head  but  does  not  transfer  data. 

To  call: 

See  Interrupt  13H  Functions  02H  and  03H. 

Returns: 

See  Interrupt  13H  Functions  02H  and  03H. 
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Function  ODH:  Alternate  Disk  Reset 

To  call: 

AH  =  ODH 

DL  =  drive  number 

Returns: 

Nothing 

Function  lOH:  Test  for  Drive  Ready 

To  call: 

AH  =  lOH 

DL  =  drive  number 

Returns: 

AH  =  status 

Function  IIH:  Recalibrate  Drive 

To  call: 

AH  =  IIH 

DL  =  drive  number 

Returns: 

AH  =  status 

Function  14H:  Controller  Diagnostic 

To  call: 

AH  =  14H 

Returns: 

AH  =  status 

Function  15H:  Get  Disk  Type 

To  call: 

AH  =  15H 

DL  =  drive  number 

Returns: 

AH  =  drive  type  code: 

OOH  no  drive  present 

OlH  cannot  sense  when  floppy  disk  is  changed 

(more) 


1522  The  M^DOS  Encyclopedia 


Appendix  O:  IBM  PC  ROM  BIOS  Calls 


02H  can  sense  when  floppy  disk  is  changed 

03H  fixed  disk 

IfAH  = 

03H: 

CX:DX 

=  number  of  sectors 

Function  16H:  Check  for  Change  of  Floppy  Disk  Status 

To  call: 

AH 

=  16H 

DL 

=  drive  number  to  check 

Returns: 

AH 

=  OOH  no  change 

06H  floppy-disk  change 

Function  17H:  Set  Disk  Type 

To  call: 

AH 

=  17H 

DL 

=  drive  number 

AL 

=  floppy-disk  type  code 

Returns: 

Nothing 


Interrupt  14H;  Serial  Port  Services 

Function  OOH:  Initialize  Port  Parameters 

To  call: 

AH  =  OOH 

AL  =  serial  port  parameters  (bit  settings  BBBPPSCC): 


baud  rate: 

000 

110  baud 

001 

150  baud 

010 

300  baud 

Oil 

600  baud 

100 

1200  baud 

101 

2400  baud 

110 

4800  baud 

111 

9600  baud 

(more) 
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PP  parity  code: 

00  none 

01  odd 

10  none 

11  even 

S  number  of  stop  bits  code: 

0  one  stop  bit 

I  two  stop  bits 

CC  character  size: 

00  unused 

01  unused 

10  7-bit  character  size 

I I  8-bit  character  size 

DX  =  serial  port  number  (0  =  first  port) 

Returns: 

Nothing 

Function  OlH:  Send  One  Character 

To  call: 

AH  =  OlH 

AL  =  character  to  send 

DX  =  serial  port  number  (0  =  first  port) 

Returns: 

AH  =  error  status  (see  Interrupt  14H  Function  03H): 

OOH  no  error 

Function  02H:  Receive  One  Character 

To  call: 

AH  =  02H 

DX  =  serial  port  number  (0  =  first  port) 

Returns: 

AL  =  character  received 

AH  =  error  status  (see  Interrupt  14H  Function  03H): 

OOH  no  error 

Function  03H:  Get  Port  Status 

To  call: 

AH  =  03H 

DX  =  serial  port  number  (0  =  first  port) 
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Returns: 

AX  =  serial  port  status: 


8000H 

time  out 

4000H 

transfer  shift  register  empty 

2000H 

transfer  holding  register  empty 

lOOOH 

break  detect 

0800H 

framing  error 

0400H 

parity  error 

0200H 

overrun  error 

OlOOH 

data  ready 

0080H 

received  line  signal  detect 

0040H 

ring  indicator 

0020H 

data  set  ready 

OOlOH 

clear  to  send 

0008H 

delta  receive  line  signal  detect 

0004H 

trailing  edge  ring  detector 

0002H 

delta  data  set  ready 

OOOIH 

delta  clear  to  send 

Note:  Multiple  conditions  can  be  active  simultaneously. 


Interrupt  15H:  Miscellaneous  System  Services 

Function  OOH:  Turn  On  Cassette  Motor 
Function  OlH:  Turn  Off  Cassette  Motor 

To  call: 

AH  =  OOH  turn  on  cassette  motor 

OlH  turn  off  cassette  motor 

Returns: 

Nothing 

Function  02H:  Read  Data  from  Cassette 

To  call: 

AH  =  02H 

CX  =  number  of  bytes  to  read 

ES:BX  =  buffer  address 
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Returns: 

CF  =0  no  error 

1  error 

AH  =  error  status  (if  needed): 

OlH  CRC  error 

02H  bit  signals  scrambled 

03H  no  data  found 

DX  =  number  of  bytes  read 

ES:BX  =  location  following  last  byte  read 

Function  03H:  Write  Data  to  Cassette 

To  call: 

AH  =  03H 

CX  =  number  of  bytes  to  write 

ES:BX  =  buffer  address 

Note:  Blocking  factor  =  256  bytes/block. 

Returns: 

CX  =00H 

ES:BX  =  location  following  last  byte  written 


Interrupt  16H:  Keyboard  Services 

Function  OOH:  Read  Next  Character 

Tocall: 

AH  =  OOH 

Returns: 

If  ASCII  characters: 

AH  =  standard  PC  keyboard  scan  code 

AL  =  ASCII  character 

If  extended  ASCII  codes: 

AH  =  extended  ASCII  code 

AL  =  OOH 

Note:  Does  not  return  until  character  is  read;  removes  character  from  keyboard  buffer. 
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Function  OlH:  Report  If  Character  Ready 

To  call: 

AH  =  OlH 

Returns: 

ZF  =0  character  ready 

1  character  not  ready 

AH  =  see  Interrupt  16H  Function  OOH 

AL  =  see  Interrupt  16H  Function  OOH 

Note:  Returns  immediately;  does  not  remove  character  from  keyboard  buffer. 

Function  02H:  Get  Shift  Status 

To  call: 

AH  =  02H 

Returns: 

AL  =  shift  status: 


OlH 

right  shift  active 

02H 

left  shift  active 

04H 

Ctrl  active 

OSH 

Alt  active 

lOH 

Scroll  Lock  active 

20H 

Num  Lock  active 

40H 

Caps  Lock  active 

80H 

insert  state  active 

Note:  Multiple  states  can  be  active  simultaneously. 


Interrupt  17H:  Printer  Services 

Function  OOH:  Send  Byte  to  Printer 

To  call: 

AH  =  OOH 

AL  =  character  to  be  printed 

DX  =  printer  number 

Returns: 

AH  =  status  (^see  Interrupt  17H  Function  02H) 
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Function  OlH:  Initialize  Printer 

To  call: 

AH  =  OlH 

DX  =  printer  number 

Returns: 

AH  =  status  {see  Interrupt  17H  Function  02H) 

Function  02H:  Get  Printer  Status 

To  call: 

AH  =  02H 

DX  =  printer  number 

Returns: 


=  status: 

OlH 

time  out 

02H 

unused 

04H 

unused 

OSH 

I/O  error 

lOH 

printer  selected 

20H 

out  of  paper 

40H 

printer  acknowledgment 

80H 

printer  not  busy  (bit  off,  0,  =  busy) 

Note:  Multiple  states  can  be  active  simultaneously. 


Interrupt  18H:  Transfer  Control  to  ROM-BASIC 
Interrupt  19H:  Reboot  Computer  (Warm  Start) 
Interrupt  lAH:  Get/Set  Time/Date 

Function  OOH:  Read  Current  Clock  Count 

To  call: 

AH  =  OOH 
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Returns: 

AL  =  midnight  signal 

CX  =  high-order  word  of  tick  count 

DX  =  low-order  word  of  tick  count 

Function  OlH:  Set  Current  Clock  Count 

To  call: 

AH  =  OlH 

CX  =  high-order  word  of  tick  count 

DX  =  low-order  word  of  tick  count 

Returns: 

Nothing 

Function  02H:  Read  Real-Time  Clock 

To  call: 

AH  =  02H 

Returns: 

CF  =0  clock  running 

1  clock  stopped 

CH  =  hours  in  BCD 

CL  =  minutes  in  BCD 

DH  =  seconds  in  BCD 

Function  03H:  Set  Real-Time  Clock 

To  call: 

AH  =  03H 

CH  =  hours  in  BCD 

CL  =  minutes  in  BCD 

DH  =  seconds  in  BCD 

DL  =  OOH  standard  time 

OlH  daylight  saving  time 

Returns: 

Nothing 

Function  04H:  Read  Date  from  Real-Time  Clock 

To  call: 

AH  =  04H 
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Returns: 

CF  =0  clock  running 

1  clock  stopped 

CH  =  century  in  BCD  (19  or  20) 

CL  =  year  in  BCD 

DH  =  month  in  BCD 

DL  =  day  in  BCD 

Function  05H:  Set  Date  in  Real-Time  Clock 

To  call: 

AH 
CH 
CL 
DH 
DL 

Returns: 

Nothing 

Function  06H:  Set  Alarm 

To  call: 

AH  =  06H 

CH  =  hours  in  BCD 

CL  =  minutes  in  BCD 

DH  =  seconds  in  BCD 

Returns: 

CF  =  status; 

0  operation  successful 

1  alarm  already  set  or.  clock  stopped 

Function  07H:  Reset  Alarm  (Turn  Alarm  OfO 

To  call: 

AH  =07H 

Returns: 

Nothing 


=  05H 

=  century  in  BCD  (19  or  20) 
=  year  in  BCD 
=  month  in  BCD 
=  day  in  BCD 
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Symbols  and  Numerals 

!  (exclamation  point) 

SYMDEB 1154-55 

#  (number  sign).  See  also  EDLIN  commands 
CREF967 
•(asterisk) 

EDLIN  829, 832 
SYMDEB  1156 
wildcard  813 
- (hyphen) 

DEBUG  prompt  1020-21, 1046 
SYMDEB  prompt  1055 
.  (period).  See  also  EDLIN  commands 
SYMDEB  1151 

.  and ..  (directory  aliases)  103,  282,  283 
/(slash) 

directories  280,  284 
SYMDEB  1150 
:  (colon) 

EDLIN  832 

hexadecimal  object  file  format  1499 
SYMDEB  1059 
;  (semicolon),  APPEND  739 
<,  >,  and  »  (redirection  symbols)  67, 753 
ECHO  759 
filters  and  430 
PAUSE  766 
REM  768 

SYMDEB  1143-45 
=  (equal  sign),  SYMDEB  1146 
?  (question  mark) 

PROMPT  904,  905 
SYMDEB  1152-53 
@  (at  sign)  1434 
\  (backslash) 

directories  284 

{  }  (braces),  SYMDEB  1147-48 
;  (piping  character)  67, 753 
ECHO  759 
REM  768 

-(tilde),  SYMDEB  1149 
86-DOS  operating  system  12-13,  27 
as  basis  for  MS-DOS  15-19 
4004.  See  Intel  4004  chip 
8008.  See  Intel  8008  chip 
8080.  See  Intel  8080  chip 
8086.  See  Intel  8086  chip 
8250.  See  INS8250  Universal  Asynchronous 
Receiver  Transmitter  (UART) 


8259.  See  Intel  8259A  Programmable  Interrupt 
Controller  (PIC) 

80186.  See  Intel  80186  chip 
80188.  See  Intel  80188  chip 
80286.  See  Intel  80286  chip 
80386.  See  Intel  80386  chip 


A 

Absolute  Disk  Read.  See  Interrupt  25H 
Absolute  Disk  Write.  See  Interrupt  26H 
Address,  defined  1058 

Advanced  run  length  limited  (ARLL)  encoding  87 
align  type  parameters  125-27 
Allen,  Paul  8(fig.),  l6(fig.) 

in  the  development  of  early  BASIC  3-8 
in  the  development  of  MS-DOS  14-15, 30, 34 
Allocate  Memory  Block.  See  Interrupt  21H 
Function  48H 

Alphabetic  Sort  Filter  (SORT)  935-37 
Altair  computer,  and  BASIC  language  3-8 
Alternate  Disk  Reset.  See  Interrupt  13H  Function  ODH 
ANSI  Console  Driver.  See  ANSI.SYS 
ANSI.SYS  152, 731-38 

AUTOEXEC.BAT  and  755 
controlling  the  screen  with  158-59 
key  and  extended  key  codes  1471-72 
APPEND  command  739-40 

MS-DOS  version  3.3 1436-37 
Append  Lines  from  Disk  (EDLIN  A)  834 
Application  programs 
structure  of  107-48 

.COM  programs  142-48 
.EXE  programs  107-42 
as  transient  447 

writing  for  upward  compatibility  489-97 
hardware  issues  489-92 
operating-system  issues  492-97 
Applications  Program  Interface.  See  Family  API 
Arithmetic,  hexadecimal  1035 
ASCII  format  872 

character  set  1465-67 
cross-reference  listing  967 
display  content  of  memory  in  1077-78 
display  lookup  table  629-40 
entering  strings  1093-96 
escape  sequences  731 
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ASCII  format  (continued ) 

make  files,  and  MAKE  utility  999-1003 
strings  with  environmental  variables  930 
text  files  752, 788, 829, 935, 947 
ASCIIZ  strings  65 
ASCTBL.C  program  545 
correct  code  639(fig.) 
correction  of  631-39 
expected  output  630(fig.) 
incorrect  code  630-31 
Assemble  Machine  Instructions 
DEBUG  A 1024-25 
SYMDEB  A 1063-64 
Assembly-language  programs 

acceptance/translation  of  1024, 1063 
active  TSR  (video  buffer  dump)  360-80 
block-device  driver  478-85 
character-device  driver  471-77 
character-oriented  filter  431-33 
communications  device  driver  182-200 
communications  port  monitor  558-63 
disassembling  machine  instructions  into 
1051, 1132 

filter  as  child  process  442-46 
handler  for  UART  interrupts  216-21 
line-oriented  fi  Iter  434 - 35 
lowercase  filter  437-39 
message  program  651 
modem  engine  207-8 
MS-DOS  shell  substitute  81-83 
parent  and  child  examples  329-34 
passive  TSR  (pop-up)  357-59 
replacement  Interrupt  OOH  handler  420-24 
replacement  Interrupt  24H  handler  395-98 
root  and  overlay  examples  337-42 
support  files  for  terminal  emulator  223-30 
symbol  cross-referencing  in,  with  GREF  967 
test  program  for  communications  port  monitor 
580-81 

translation  into  relocatable  object  module  isee 
Microsoft  Macro  Assembler) 
volume  label  updating  program  292-96 
ASSIGN  command  741-42 
APPEND  and  739 
BACKUP  and  747 
CHKDSKand775 
DISKCOMP  and  818 
DISKCOPYand822 
JOIN  and  877 
LABEL  and  882 
MKDIR/MD885 

Assign  Drive  Alias  (ASSIGN)  741-42 

Assign  Standard  Input/Output  Device  (CTTY)  810 

Asynchronous,  defined  171-72 


AT  address  parameter  128 
AT  Probe  hardware  debugging  aid  641 
ATTRIB  command  743-44 
MS-DOS  version  3-3 1437 
AUTOEXEC.BAT  file  (BATCH)  755-57 
environments  and  65 
MODE  and  887 
VERand952 

AUX  (auxiliary  input/output)  22,  59, 62, 151.  See  also 
COMl;  Serial  communications  ports 
filters  and  429 

implementing  modem  engine  with  MS-DOS 
functions  168-70 
1/0161-62 
opening  76 

Auxiliary  Input.  See  Interrupt  21H  Function  03H 
Auxiliary  Output.  See  Interrupt  21H  Function  04H 


B 

Background  program  900 
BACKUP  command  745-51 
ASSIGN  and  741 
ATTRIB  and  743 
JOIN  and  877 
MS-DOS  version  3.3 1437 
RESTORE  and  918 
Back  Up  Files  (BACKUP)  745-51 
BACKUPID.@@@  control  file  746-47 
BADSCOP.  ASM  program  544 
correction  of  593-600 
incorrect  version  of  587-93 
.  BASIC  (language),  role  of,  in  development  of 
MS-DOS  3-8, 12, 14 
Batch  file(s)  26 

AUTOEXEC.BAT  755-57 
COMMAND.COM  and  64, 66-67, 78, 753, 755 
directives  730, 752-69, 1434 
@  command  1434 
CALL  command  1434-35 
ECHO  command  758-59 
FOR  command  760-61 
GOTO  command  762-63 
IF  command  764-65 
PAUSE  command  766-77 
REM  command  768 
SHIFT  command  769 
executing  commands  stored  in  752 
MS-DOS  version  3.3 1434-35 
suspend  execution  of  766 
.BAT  file.  See  Batch  file(s) 

Baud  rate  170, 222, 892 
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BDOS  (Basic  Disk  Operating  System),  CP/M  10 
Bebic,  Mark  39 

Binary  operators,  SYMDEB 1059 
Binary-to-hexadecimal  file  conversion  utility 
program  1503-5 

BIOS  (Basic  Input/Output  System) 

CP/M  10 

MS-DOS  52-53,  61-62 

ROM  62  isee  also  Interrupts  lOH  through  lAH) 
BIOS  parameter  block  (BPB)  70, 71(fig.),  93 
build  function,  in  device  drivers  459-60 
format  460(table) 

Bit  bucket.  See  NUL  device 
Bit  parity  222 

Bit  rate  divisor  table  for  8250  IBM  UART  chip 
175(table) 

Bits  per  second  (bps)  170 

Block  device(s)  57, 62.  See  also  Fixed  disk;  Floppy 
disk;  RAMdisk 

critical  error  handling  392-93 
drivers  450-52 
file  system  and  54-55 
layout  of  a  physical  86-90 
partition  layout  90-92 
setting  highest  logical  803 
setting  parameters  797-98 
Bootable  devices,  loading  70, 71(fig.) 

Boot  sector  94-96 

hexadecimal  dump  of  96(fig.) 
map  of  95(fig.) 

Bootstrapping,  operating  system  52, 68-72 
BOUND  Range  Exceeded  exception.  See 
Interrupt  05H 
BREAK  command  770-71 
BREAK  command  (CONFIG.SYS)  788,  790 
BREAK  condition  172 
Breakpoints  1033 

clearing  1065-66 
DEBUG  use  of  578-79,  584-85 
disabling  1067-68 
enabling  1069-70 
hardware  640, 641 
listing  1071 
setting  1072-73 
SYMDEB  use  of  608-9 
trapping  400 

Breakpoint  Trap  exception.  See  Interrupt  03H 
Brock,  Rod  12, 15 

Buffered  Keyboard  Input.  See  Interrupt  21H 
Function  OAH 

BUFFERS  command  (CONFIG.SYS)  788,  791 
Byte(s) 

displaying  1079-80 


Byte(s)  (continued ) 
entering  1095-96 
BYTE  alignment  125-26 


c 

CALL  command  (BATCH)  1434-35 
Calls  menu  (CodeView)  1162 
Cancel  Assign-List  Entry  1411-12 
Cassette/Network  Service.  See  Interrupt  15H 
CAV  (constant  angular  velocity)  disks  87 
C  Compiler,  Microsoft 

environmental  variables  in  931, 980 
general  structure  of  C  program  139(fig.) 
memory  model  use  with  137-40 
utilities  supplied  with  974, 977, 987, 999 
CCP  (Console  Command  Processor),  CP/M  10 
CD  command.  See  CHDIR/CD  command 
CD  ROM  storage  103 

CDVUTL.C  communications  driver-status 
utility  209-15 
code  209-14 

program  functions  2l4(table) 

Central  processing  unit  (CPU),  speed  of,  and 
compatibility  issues  491 
CHl.ASM  program  215-22 

exception  handler  module  223-24 
module  functions  221(table) 
set-mdm()  parameter  coding  222(table) 
CH2.ASM  program  225-30 
Change  Code  Page  (CHCP)  1440 
Change  Current  Directory.  See  Interrupt  21H 
Function  3BH 

Change  Current  Directory  (CHDIR  or  CD)  772-73 
Change  File  Attributes  (ATTRIB)  743-44 
Change  Filename  (RENAME  or  REN)  912-13 
Change  Sharing  Retry  Count  1337-38 
Character-device  input/output  149-66.  See  also 

Display  output;  Graphics;  Input/output 
(I/O);  Parallel  port;  Printer;  Screen; 
Serial  communications  ports 
accessing  character  devices  150-51 
background  information  on  149-50 
basic  MS-DOS  devices  151 
display  157-61 
keyboard  154-57 
parallel  port  and  printer  163-64 
raw  versus  cooked  mode  153-54 
serial  communications  ports  161-62 
standard  devices  152-53 
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Character-device  input/output  (continued ) 
basic  MS-DOS  devices  (continued ) 
standard  devices  as  support  for  filters 
429-30 

copying  files  806-9 
critical  error  handling  393 
defined  keyboard  879 
device  drivers  448-50 
lOCTL  subfunctions  164-66 
screen  dump  in  graphics  mode  to  printer 
874-76 

specify  for  standard  input/output  810 
system  calls  for  1182 

Character-device  management  commands  728 
CLS781 
CTTY810 
GRAFTABL  872-73 
KEYBjo:  879-81 
MODE  887-95 
PRINT  899-903 

Character  Input  with  Echo.  See  Interrupt  21H 
Function  OlH 

Character  Input  Without  Echo.  See  Interrupt  21H 
Function  08H 

Character  Output.  See  Interrupt  21H  Function  02H 
Character  string,  finding  863-64 
CHCP  command  1440 
CHDIR/CD  command  281,  772-73 
Check  Disk  Status  (CHKDSK)  774-80 
Check  for  Change  of  Floppy  Disk  Status.  See 
Interrupt  13H  Function  l6H 
Check  If  Block  Device  Is  Remote.  See  Interrupt  21H 
Function  44H  Subfunction  09H 
Check  If  Block  Device  Is  Removable.  See  Interrupt 
21H  Function  44H  Subfunction  08H 
Check  If  Handle  Is  Remote.  See  Interrupt  21H 
Function  44H  Subfunction  OAH 
Check  Input  Status.  See  Interrupt  21H  Function  44H 
Subfunction  06H 

Check  Keyboard  Status.  See  Interrupt  21H 
Function  OBH 

Check  Output  Status.  See  Interrupt  21H  Function  44H 
Subfunction  07H 
CHILD.  ASM  program  334-35 
Child  programCs) 

filters  used  as  441-46 
using  EXEC  to  load/run  321 
examining  return  codes  328 
parent  and  child  program  example  329-35 
preparing  parameters  for  323-26 
running  child  programs  327 
CHKDSK  command  101,  774-80,  941 
C  language  programs 

ASCII  lookup  program  639 


C  language  programs  (continued ) 
attribute  listing  program  291-92 
character-oriented  filter  433 
control  program  for  communications  port 
monitor  565-66 

debugging  with  SYMDEB  600-618 
demonstration  Windows  program  513-15 
driver-status  utility  209-14 
line-oriented  filter  436 
lowercase  filter  438-39 
new  FIND  filter  program  439-41 
object  module  dump  utility  1509-12 
terminal  emulator  230-41 
class  type  parameters  128-30 
Clear  Breakpoints  (SYMDEB  BC)  1065-66 
Clear  Screen  (CLS)  781 
Clipboard  (Windows)  537-38 
Clock 

setting  date  811 
setting  system  time  942 
CLOCKS  57,  59, 62, 151 
Closed-loop  servomechanism  89 
Close  File.  See  Interrupt  21H  Function  3EH 
Close  File  with  FCB.  See  Interrupt  21H  Function  lOH 
CLPBRD  utility  (Windows)  506 
CLS  command  781 
Clusters,  file  data  94 
CLV  (constant  linear  velocity)  disks  87 
Cmacros  1178-81 
CMACROSX.INC  1179-81 
COBOL  (language)  14 
Code-page  switching  1438-48, 1451-58 
CodeView  utility  573,  619-40, 1157-73 
description  1158-59 
dialog  window  commands  1163-65 
display  window  commands  1159-62 
Calls  menu  1162 
File  menu  1159 
Help  menu  1162 
Language  menu  ll6l 
Options  menu  ll6l 
Run  menu  ll60 
Search  menu  ll60 
View  menu  1160 
Watch  menu  ll6l 

instrumentation  debugging  with  619-29 
key  commands  1163 
messages  1166-73 
screen  1159(fig.) 

screen  output  debugging  with  629-40 
Cold  boot  68 

Color  capabilities,  of  display  733 
Color/Graphics  Adapter  (CGA)  157 
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COMl  (first  serial  communications  port)  151, 161-62 
COM2  (second  serial  communications  port)  151, 
161-62 

combine  type  parameters  127-28 
COMDEF  Communal  Names  object  record  651, 
698-700 

COMDVR.  ASM  communications  device  driver 
182-206 
buffering  203 
code  182-200 

debugging  techniques  205-6 
definitions  200-201 
headers  and  structure  tables  201 
Initialization  Request  routine  204-5 
interrupt  service  routine  203-4 
Start-output  routine  204 
strategy  and  request  routines  180 
using  205 

COMENT  Comment  object  record  651, 658-60 
Command(s)  725-30.  See  individual  command 
names 

defining  command  search  path  897 
execution  of,  with  COMMAND.COM  64-65 
by  functional  group  728-30 
internal,  external,  and  batch  76-79 
interpreting  text  file  of,  with  MAKE  999 
PC-DOS,  added  to  MS-DOS  version  3  3 
1435-36 

COMMAND.COM  20, 63-68,  782-84 

batch  files  and  64, 66-67, 78, 753, 755-56 

command  execution  with  64-65 

define  prompt  904 

escape  to  1154-55 

EXEC  use  with  329-30 

I/O  redirection  in  67-68 

loading  76-79 

MS-DOS  environments  and  65-66 
parts  of  76 

specifying/replacing,  with  SHELL  79-83, 804 
split  personality  of  64 
SYS  and  940 
terminating  853 

transient/resident  portions  of  24 
COMMAND  command  782-84.  See  also 
COMMAND.COM 

Command  processor.  See  COMMAND.COM;  SHELL 
command 

Command  Processor  (COMMAND)  782-84 
Command  tail 

in  child  program  execution  327 
DEBUG  initializing  of  582-83 
FCB  functions  and  267-68 
name  parameters  1040, 1116 


COMMDUMP.BAS  program  543-44,  569-72 
Comment  line 

including  with  REM  768 
in  make  files  1001 
SYMDEB 1156 
Commit  File  1450-51 
COMMON  parameter  128 
COMMSCMD.BAS  program  543,  567-69 
COMMSCMD.C  program  543 

as  a  .COD  file  for  SYMDEB  debugging  601-6 
correction  of  606-18 
stopping  a  trace  in  565-66 
COMMSCOP.ASM  program  542-43,  558-63 
Communications,  interrupt-driven  167-246, 412 
device  driver  180 
hardware  for  170-80 

8250  UART  architecture  172-80 
modem  170-71 
serial  port  171-72 

memory-resident  device  driver  182-215 
COMDRV.ASM  182-206 
driver-status  utility  CDVUTL.C  209-15 
modem  engine  206-9 
vs  traditional  method  181 
program,  purpose  of  167-68 
traditional  device  driver  215-46 
exception  handler  module  223-25 
hardware  ISR  module  215-22 
smart  terminal  emulator  CTERM.C  230-46 
video  display  module  225-30 
using  simple  MS-DOS  functions  168-70 
Compact  memory  model  138 
COMPAQ-DOS  operating  system  27 
Compare  Files  (COMP)  785-87 
Compare  Files  (FC)  854-57 
Compare  Floppy  Disks  (DISKCOMP)  818-21 
Compare  Memory  Areas 
DEBUG  C 1026 
SYMDEB  C 1074 
Compatibility  issues 

8086/8088  and  80286 1507-8 
MS-DOS  and  MS  OS/2  489-97 
hardware  489-92 
operating  system  492-97 
COMP  command  785-87 
MS-DOS  version  3  3 1435 
Compress  .EXE  File  (EXEPACK)  977-79 
.COM  program  files  23, 64, 142-47, 974 

converting  .EXE  programs  to  executable 
971-72 
creating  144-46 
vs  .EXE  programs  147-48 
giving  control  to  143 
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.COM  program  files  (continued) 

memory  allocated  for  142, 300-302 
memory  map  with  register  pointers  l43(fig.) 
patching  using  DEBUG  146 
terminating  144 
COMSPEC  variable  930 

CON  (console  input/output)  22,  59,  62, 151, 157.  See 
also  Display  output;  Screen 
batch  commands  for  66-67 
filter  and  429 
opening  76 

Conditional  execution,  using  IF  to  perform  764-65 
CONFIG.SYS  system  configuration  63, 448, 788-89 
configuring  Control-C  checking  790 
configuring  internal  disk  buffers  791-92 
configuring  internal  stacks  805 
environments  and  65 
installing  device  drivers  149, 795-96 
setting  block-device  parameters  797-98 
setting  country  code  793-94 
setting  highest  logical  drive  803 
setting  maximum  open  files  with  FCBs  799-800 
setting  maximum  open  files  with  handles  801-2 
specifying  command  processor  804 
Configurable  External-Disk-Drive  Driver 
(DRIVER.SYS)  826-28 
Configure  Control-C  Checking  (BREAK)  790 
Configure  Device  (MODE)  887 
Configure  Fixed  Disk  (FDISK)  858-62 
Configure  Internal  Disk  Buffers  (BUFFERS)  791 
Configure  Internal  Stacks  (STACKS)  805 
Configure  Printer  (MODE)  888-89 
Configure  Serial  Port  (MODE)  892-93 
Configure  System  Disk  for  a  Specific  Country 
(SELECT)  925-29 
Console.  See  Keyboard;  Screen 
Control-Break,  exception  handling  385, 386, 387, 389 
Control-Break  (user  defined).  See  Interrupt  IBH 
Control-C 

configuring  check  790 
setting  check  770 

Control-C  exception  handler  385, 386-89 
customizing  387-89 
processing  Control-C  389 
Control-C  Handler  Address.  See  Interrupt  23H 
Controller  Diagnostics.  See  Interrupt  13H 
Function  14H 

CONTROL  Panel  (Windows)  507 
Control-2  in  EDLIN  commands  846 
Conventional  memory  297-305, 907 

block  move  from  extended  memory  to  318-19 
functions  to  support  299(table) 
using  functions  in  300-305 


Convert  .EXE  File  to  Binary-Image  File  (EXE2BIN) 
971-73 

Cooked  versus  raw  mode  153-54 
Coprocessor  Error  exception.  See  Interrupt  lOH 
Coprocessor  Not  Available  exception.  See 
Interrupt  07H 

Coprocessor  Segment  Overrun  exception.  See 
Interrupt  09H 
COPY  command  806-9 
ASSIGN  and  741 
batch  files  and  752 
DISKCOPYand822 
escape  sequences  using  732 
Copy  File  or  Device  (COPY)  806-9 
Copy  Files  (XCOPY)  955-59 
Copy  Floppy  Disk  (DISKCOPY)  822 
Copy  Lines  (EDLIN  C)  835-36 
Country,  configure  disk  for  a  specific  925-29 
COUNTRY  command  (CONFIG.SYS)  788,  793-94 
BACKUP  and  747 
development  of  36 
MS-DOS  version  3.3 1442-43 
setting  date  812 
setting  time  942 

CP/M  operating  system  8, 9-10,  56, 142 
compatibility  with  63 
competition  with  MS-DOS  27-29 
file  management  30-31 

Create  Directory.  See  Interrupt  21H  Function  39H 
Create  .EXE  File  (LINK)  987-98 
Create  File  with  FCB.  See  Interrupt  21H  Function  l6H 
Create  File  with  Handle.  See  Interrupt  21H 
Function  3CH 

Create  New  File.  See  Interrupt  21H 
Function  5BH 

Create  New  Program  Segment  Prefix.  See  Interrupt 
21H  Function  26H 

Create  Symbol  File  for  SYMDEB  (MAPSYM)  1004-6 
Create  Temporary  File.  See  Interrupt  21H 
Function  5AH 
CREF  utility  967-70 
Critical  error  handler  390-98 
customized  394-98 
mechanics  of  392-93 
processing  393-94 
in  TSR  programs  353-55 
Critical  Error  Handler  Address.  See  Interrupt  24H 
CTERM.C  terminal  emulator  program  230-46 
functions  242-43(table) 
prototype  file  CTERM.H  243-44(fig.) 
Ctrl-Break.  See  Control-Break 
Ctrl-C.  See  Control-C 

Ctrl-Z.  See  Control-Z  in  EDLIN  commands 


1538  The  MS-DOS  Encyclopedia 


Subject 


CTTY  command  810 
Cursor  movement,  escape  sequences  to 
control  732-33 
Cylinder,  disk  88 


D 

Data 

entering  into  memory  1029, 1091 
moving  (copying)  1039, 1115 
sharing/exchange  in  Windows  537-38 
Data  area,  DEBUG  initializing  582 
Data  files,  setting  a  search  path  for.  See  APPEND 
command 
DATE  command  811-12 
Debugging  in  MS-DOS  541-642 
art  of  546 

communications  device  driver  205-6 
hardware  debugging  aids  640-42 
inspection  and  observation  546-49 
instrumentation 
external  555-72 
internal  549-55 

software  debugging  monitors  573-640 

CodeView  573, 619-40  {.see  also  CodeView 
utility) 

DEBUG  573,  574-86  {see  also  DEBUG 
utility) 

SYMDEB  573,  586-618  {see  also  SYMDEB 
utility) 

summary  of  example  programs  to  illustrate 
541-45 

DEBUG  utility  113,  573,  574-86, 1020-53 
A  command  141,  577, 1021, 1024-25 
basic  techniques  574-81 
breakpoints  578-79,  584-85 
C  command  1021, 1026 
D  command  1021, 1027-28 
E  command  l4l,  1021, 1029-30 
establishing  initial  conditions  581-83 
F  command  1021, 1031-32 
G  command  577,  584-85, 1021, 1033-34 
H  command  1021, 1035 
I  command  1021, 1036 
L  command  1021, 1037-38 
M  command  577, 1021, 1039 
N  command  1021, 1040-41, 1052 
O  command  1021, 1042 
patching  .COM  programs  with  146 
patching  .EXE  programs  with  585-86, 141-42 
P  command  580, 1021, 1043 


DEBUG  utility  (continued) 

Q  command  142, 1021, 1044 
R  command  142,  576, 1021, 1045-47 
S  command  1021, 1048-49 
T  command  576, 1021, 1050 
U  command  577, 1021, 1051 
using  Write  commands  585-86 
W  command  141,  577,  585-86, 1021, 1052-53 
Define  Command  Search  Path  (PATH)  897-98 
Define  Keyboard  (KEYBa::v)  879-81 
Define  System  Prompt  (PROMPT)  904-6 
DEL/ERASE  command  813-14 
Delete  File.  See  Interrupt  21H  Function  13H;  Interrupt 
21H  Function  41H 
Delete  File  (DEL  or  ERASE)  813-14 
Delete  Lines  (EDLIN  D)  837-38 
Desk-checking  547 
Development  of  MS-DOS  3-45 
before  MS-DOS  3-15 
creating  MS-DOS  15-19 
future  of  MS-DOS  45 
hardware  and  27-28 
international  market  and  35-37 
software  and  38 
versions  1.x  20-29 
versions  2.x  30-38 
versions  3.x  39-44 

DEVICE  command  (CONFIG.SYS)  149-50, 788, 
795-96 

MS-DOS  version  3.3 1443-45 
Device  driver(s)  52-53,  57 
Device  driver(s),  installable  180, 447-86.  See  also 
ANSI.SYS;  Block  device(s);  Character- 
device  input/output;  RAMDRIVE.SYS; 
VDISK.SYS 

development  of,  in  MS-DOS  version  2.0 
32-33 

loading/initializing  74, 75(fig.) 
processing  of  a  typical  I/O  request  468-69 
relationship  to  resident  448-50 
structure  of  450-68 
device  header  450-52 
interrupt  routine  453-68 
strategy  routine  452-53 
writing  469-86 

TEMPLATE  example  471-78 
TINYDISK  example  478-86 
Device  driver,  installable  communications  package 
180, 182-215 

memory-resident  generic 
CDVUTL.C  utility  209-15 
COMDVR.  ASM  device  driver  182-206 
modem  engine  206-9 
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Device  driver,  installable  communications  package 
(continued) 

memory-resident  generic  (continued) 
vs  traditional  method  181 
traditional  215-46 

exception-handler  module  223-25 
hardware  ISR  module  215-22 
terminal  emulator  CTERM.C  230-46 
video  display  module  225-30 
Device  driver(s),  resident  62 

relationship  to  installable  device  drivers  448-50 
Device  header  450-52 

device  attribute  word  in  452(table) 

DGROUP  718-21 
Dialog  boxes  (Windows)  504-5 
Dialog  window  commands  (CodeView)  1163-65 
Digital  Equipment  Corporation  (DEC)  28 
Digital  Research,  development  of  CP/M  9-10, 12,  28 
DIR.  ASM  program  288-90 
DIR  command  815-17 
DIRDUMRC  program  291-92 
Direct  Console  I/O.  See  Interrupt  21H  Function  06H 
Direct  memory  access.  See  DMA  (direct  memory 
access)  controller 

Directory  101-3,  279-96.  See  also  Subdirectory; 
Volume  label(s) 
alias  103,  282,  283 
analyzing  for  errors  774 
attribute  field  282(fig.) 
changing  current  772 
copying  955 
current  281,  288 
date/time  fields  283(fig.) 
displaying  815 
displaying  structure  944 
format  281-83 

functional  support  for  284-96 
creating/deleting  287 
examining/modifying  287 
MS-DOS  functions  for  accessing 
284-86(table) 

programming  examples  288-92 
searching  286 
specifying  current  288 
wildcard  characters  286-87 
hexadecimal  dump  of  102(fig.) 
initializing  865 
joining  to  disk  877 
making  885 
removing  923 
root  (^see  Root  directory) 
structure  32,  54,  279(fig.),  280-81 


Directory  (continued ) 
system  calls  for  1183 
Directory  management  commands  729 
APPEND  739-40 
CHDIR/CD  772-73 
MKDIR/MD  885-86 
PATH  897-98 
RMDIR/RD  923-24 
TREE  944-46 

Disable  Breakpoints  (SYMDEB  BD)  1067-68 
Disable  Source  Display  Mode  (SYMDEB  S  -)  1128 
Disassemble  (Unassemble)  Program 
DEBUG  U 1051 
SYMDEB  U 1132-33 

Disk 

checking  status  of  774 
con  figuring  for  a  specific  country  925 
configuring  internal  buffer  791 
directories  {see  Directory) 
displaying  volume  label  944-45 
fixed  isee  Fixed  disk) 
floppy  isee  Floppy  disk) 
initialize  865 
joining  to  directory  877 
name  isee  Volume  labells]) 
recovering  files  from  damaged  910 
structure  of  85-103 
virtual  907, 948 
writing  file/sectors  to  1052 
Disk  cache,  configure  791 
Disk  Parameter  Pointer.  See  Interrupt  lEH 
DISKCOMP  command  818-21 
ASSIGN  and  741 
JOIN  and  877 

DISKCOPY  command  822-25 
ASSIGN  and  741 
JOIN  and  877 

Disk  management  commands  729 
ASSIGN  741-42 
DISKCOMP  818-21 
DISKCOPY  822-25 
FORMAT  865-71 
LABEL  882-84 
SUBST  938-39 
SYS  940-41 
VERIFY  953 
VOL  954 

Disk  management  system  calls  1182 
Disk  Reset  1213-14 
Disk  Services.  See  Interrupt  13H 
Disk  transfer  area  (DTA) 
default  267-68 
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Disk  transfer  area  (continued) 

getting  address  isee  Interrupt  21H 
Function  2FH) 

setting  address  isee  Interrupt  21H 
Function  lAH) 

TSR  programs  353 

Display  10-Byte  Reals  (SYMDEB  DT)  1087-88 
Display  ASCII  (SYMDEB  DA)  1077-78 
Display  by  Screenful  (MORE)  896 
Display  Bytes  (SYMDEB  DB)  1079-80 
Display  Directory  (DIR)  815-17 
Display  Directory  Structure  (TREE)  944-46 
Display  Disk  Name  (VOL)  954 
Display  Doublewords  (SYMDEB  DD)  1081-82 
Display  File  (TYPE)  947 
Display  in  Pages  (EDLIN  P)  844 
Display  Long  Reals  (SYMDEB  DL)  1083-84 
Display  Memory 

DEBUG  D 1027-28 
SYMDEB  D 1075-76 
Display  Memory  Areas  1075-76 
Display  or  Modify  Registers 
DEBUG  R 1045-47 
SYMDEB  R 1122-24 

Display  output  157-60.  See  also  Character-device 
input/output;  CON;  Screen 
of  batch-file  execution  758 
CH2.ASM  communications  module  225-30 
color  capability  of  733 
controlling  the  screen  158-59 
cursor  movement  control  732-33 
debugging  with  CodeView  629-40 
erasing  733 
graphics  attributes  734 
in  pages  844 

programming  examples  l60 
role  of  ROM  BIOS  in  159 
by  screenful  896 
setting  mode  890-91 
width  733 
wrap  around  733 

Display  Short  Reals  (SYMDEB  DS)  1085-86 
Display  Source  Line  (SYMDEB .)  1151 
Display  String.  See  Interrupt  21H  Function  09H 
Display  Text  (ECHO)  758 
Display  Version  (VER)  952 
Display  window  commands  (CodeView)  1159-62 
Display  Words  (SYMDEB  DW)  1089-90 
Divide  by  Zero  exception.  See  Interrupt  OOH 
DIVZERO.ASM  program  419, 420-24 
DMA  (direct  memory  access)  controller  69 
/DOSSEG  switch,  LINK  use  of  718-19 
Double-Fault  Exception.  See  Interrupt  08H 


Doublewords 

displaying  1081 
entering  1097 
Drive(s) 

assigning  aliases  741-42 
substituting  for  subdirectory  938 
DRIVER.SYS  826-28 

DRIVPARM  command  (CONFIG.SYS)  788, 797-98 
/DSALLOCATE  switch,  LINK  use  of  719-21 
Dump.  See  Display  Memory 
Duplicate  File  Handle.  See  Interrupt  21H 
Function  45H 

Dynamic  Data  Exchange  (DDE)  538 


E 

EBCDIC  character  set  1469-70 
ECHO  command  (BATCH)  66, 753;  758-59 
and  PAUSE  766 

Edit  Line  (EDLIN  linenumber)  832-33 
EDLIN  commands  730, 829-52 
A  command  834 
C  command  835-36 
D  command  837-38 
E  command  839 
escape  character  in  732 
I  command  840 
L  command  841 
linenumber  command  832-33 
M  command  842-43 
P  command  844 
Q  command  845 
R  command  846-47 
S  command  848-49 
T  command  850-51 
W  command  852 

Enable  Breakpoints  (SYMDEB  BE)  1069-70 
Enable  Source  and  Machine  Code  Display  Mode 
(SYMDEB  S&)  1129 

Enable  Source  Display  Mode  (SYMDEB  S+)  1127 
End  Editing  Session  (EDLIN  E)  839 
ENGINE.  ASM  program  207-8 
Enhanced  Graphics  Adapter  (EGA)  157 

MS-DOS  version  3.3  code-page  switching  1447 
Enter  10-Byte  Reals  (SYMDEB  ET)  1102-3 
Enter  ASCII  String  (SYMDEB  EA)  1093-94 
Enter  Bytes  (SYMDEB  EB)  1095-96 
Enter  Comment  (SYMDEB  *)  1156 
Enter  Data 

DEBUG  E 1029-30 
SYMDEB  E 1091-92 
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Enter  Doublewords  (SYMDEB  ED)  1097 
Enter  Long  Reals  (SYMDEB  EL)  1098-99 
Enter  Short  Reals  (SYMDEB  ES)  1100-1101 
Enter  Words  (SYMDEB  EW)  1104 
Environment(s) 

in  child  program  execution  326-27 
MS-DOS  operating  51-52, 65-66 
Environment  variable,  set  930 
Equipment  Information.  See  Interrupt  IIH 
ERASE.  See  DEL/ERASE  command 
Error  codes 

device-driver  454(table) 
extended,  in  MS-DOS  version  3  3 1461-63 
MS-DOS,  MS  OS/2  compatibility  495 
Error  handling.  See  also  Critical  error  handler; 

Extended  error  information 
file  control  block  269 
file  handle  function  250-51 
Error  messages  24-25 
Escape  (Esc)  characters  731 

in  CTERM.C  terminal  emulator  244-45 
Escape  sequences,  controlling  screen  display  with 
731-36 

Escape  to  Shell  (SYMDEB !)  1154-55 
Evans,  Eric  37, 39 

Examine  Symbol  Map  (SYMDEB  X)  1138-39 
Exception  handler(s)  385-408 

communications  device  driver  223-25 
Control-C  handler  386-89 
critical  error  handler  390-98 
extended  error  information  401-8 
hardware-generated  exception  interrupts 
398-400 

overview  of  385-86 
EXE2BIN  utility  144, 971-73 
EXEC  function  321-43.  See  also  Interrupt  21H 
Function  4BH 
functioning  of  322-23 
loading  external  commmands  with  79 
loading  overlays  with  336-41 
loading  and  executing  336-37 
making  memory  available  335-36 
preparing  parameters  336 
program  example  337-42 
loading  programs  with  323-35 
making  memory  available  323 
parent  and  child  program  example  329-33 
preparing  parameters  323-26 
running  child  programs  327-29 
using  COMMAND.COM  with  328-29 
loading  shell  program  with  328 
running  SORT  as  a  child  process  with  442-46 
EXECSORT  ASM  program  442-46 


Execute  Command  on  File  Set  (FOR)  760-61 
EXEMOD  utility  974-76 
EXEPACK  utility  977-79 
.EXE  program  files  23, 64, 107-42 
compressing  977 
vs  .COM  programs  147-48 
controlling  the  structure  of 

MASM  GROUP  directive  131-32 
MASM  SEGMENT  directive  125-30 
sample  program  132-37 
converting  to  binary  memory-image  and  .COM 
files  971 

creating  with  LINK  643-44(fig.)  isee  also 
Object  Linker) 
giving  control  to  108-15 

preallocated  memory  112-13 
program  segment  prefix  108-11 
registers  113-15 
stacks  111-12 
loading  124-25 

memory  allocated  to  300, 302-3 
memory  diagram  137(fig.) 
memory  map  report  136-37(fig.) 
memory  map  segments  {see  Memory  segments) 
memory  models  and  137-40 
modifying  file  header  with  EXEMOD  140-41, 
974-76 

patching  with  DEBUG  141-42,  585-86 
structure  of  119-24 
file  header  119-24 
load  module  124 
terminating  115-19 

RET  instruction  118-19 
Terminate  Process  function  119 
Terminate  Process  with  Return  Code 
function  115-17 

Terminate  Program  interrupt  117 
terminating  and  staying  resident  119 
Warm  Boot/Terminate  vector  117-18 
Windows  construction  of  518-20 
EXIT  command  853 
Expanded  memory  907-8, 305-16 
checking  for  307 - 9 
manager  305-6 

relationship  to  conventional  memory  306(fig.) 
using  the  manager  309-16 
error  codes  313-l4(table) 
program  skeleton  3l4-15(fig.) 
software  interface  to  application  programs 
provided  by  310-12(table) 

Expanded  Memory  Specification  (EMS)  305 
EXP.BAS  programs  542 

corrected  code  554-55 
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EXP.BAS  programs  (continued ) 
incorrect  code  550-51 

EXTDEF  External  Names  Definition  object  record 
651, 663-64 

Extended  error  information  401-8 

Function  59H  and  newer  system  calls  406-8 
Function  59H  and  older  system  calls  405-6 
MS-DOS  version  3.3 1461-63 
MS-DOS  versions  2.0  and  3.0  401-5 
TSR  set/get  functions  352 
Extended  memory  316-19, 907 

block  move  descriptor  table  format  317(table) 
PC/AT  ROM  BIOS  Interrupt  15H  functions 
316-17, 3l6-17(tables) 

program  transferring  data  from,  to  conventional 
memory  318-19 

External  disk  drive,  configurable  driver  for  826 


F 

Family  API  489-90 
FASTOPEN  command  1433-34 
FCBS  command  (CONFIG.SYS)  44, 788, 799-800 
FC  command  785, 854-57 
FDISK  command  92, 858-62 
MS-DOS  version  3.3 1437 
File  allocation  table  (FAT)  54, 97-101 
analyze  for  errors  774, 775 
assembly-language  routine  to  access  12-bit  and 
l6-bit  100(figs.) 
development  of  8, 13,  23 
initialize  865 

relationship  to  file  data  area  98, 99(fig.) 
space  allocation  98(fig.) 

File(s)  and  file/record  management  247-78.  See  also 
Batch  file(s);  .COM  program  files;  .EXE 
program  files 

attribute  getting/setting  261-62 
backing  up  745-51 
changing  name  912 

changing  read-only/archive  attributes  743 
closing 

with  FCBs  271 
with  handles  255-56 
comparing  785-87, 854-57 
copying  806, 955 
creating 

with  FCBs  269 
with  handles  251-53 
date/time  getting  and  setting  262 
date/time  stamping  of  25 


File(s)  and  file/record  management  (continued) 
delete/erase  command  and  813 
deleting 

with  FCBs  276-77 
with  handles  260-61 
displaying  947 

duplicating/redirecting  handles  262-63 
error  handling 
with  FCBs  269 
with  handles  250-51 

file  control  block  isee  File  control  blocks) 
finding  size  of,  and  testing  for  existence  277 
getting/setting  file  attributes  261-62 
getting/setting  file  date  and  time  262 
handles  isee  File  handles) 
hidden  774, 940-41 
historical  perspective  247-48 
loading  1037, 1113 

MS-DOS  version  3  3  changes  1433-35, 1448-51 
names  isee  Filenames) 
opening  existing 
with  FCBs  270-71 
with  handles  253  -  55 

positioning  the  read/write  pointer  258-59 
reading  and  writing 
with  FCBs  271-75 
with  handles  256-58 
recovering  910 
renaming 

with  FCBs  275-76 
with  handles  260 
restoring  backup  918 
setting  maximum  open  799-800, 801-2 
system  calls  for  1182-83 
transferring  system  940 
transferring  with  EDLINT  850 
updating  914 

writing  file  or  sectors  1052, 1136 
File  control  blocks  (FCBs)  22,  32,  38, 44,  247,  263-77 
closing  files  271 
compatibility  issues  494 
creating  files  269 
DEBUG  initializing  582-83 
default,  in  executing  child  programs  327 
deleting  files  276-77 
error  handling  and  269 
extended  266-67 

finding  file  size  and  testing  for  existence  277 

opening  files  270-71 

parsing  filenames  268-69 

program  segment  prefixes  and  267-68 

reading/writing  files  271-75 

renaming  files  275-76 
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File  control  blocks  (continued ) 

setting  maximum  open  files  using  799-800 
structure  of  264-67 

extended  1475(table),  I476(fig.) 
normal  1473(fig.),  l474-75(table) 

File  data  area  103 

relationship  to  FAT  98, 99 
File  handles  32,  38,  56, 801-2,  247-63 
closing  a  file  255-56 
creating  a  file  251-53 
deleting  a  file  260-61 

duplicating  and  redirecting  handles  262-63 
error  handling  250-51 
getting/setting  date  and  time  262 
getting/setting  file  attributes  261-62 
opening  an  existing  file  253-55 
positioning  the  read/write  pointer  258-59 
reading  and  writing  with  256-58 
renaming  a  file  260 
File  header  119-24 

modify  with  EXEMOD  974-76 
segmented  (new)  .EXE  format  1487-97 
File  management  commands  728 
ATTRIB  743-44 
BACKUP  745-51 
COMP  785-87 
COPY  806-9 
DEL/ERASE  813-14 
EDLIN  829-52 
FC  854-57 
RECOVER  910-11 
RENAME/REN  912-13 
REPLACE  914-17 
RESTORE  918-22 
TYPE  947 
XCOPY  955-59 

File  management  system,  MS-DOS 
networking  and  44 
versions  2.x  30-32 
File  menu  (CodeView)  1159 
Filenames  101 

common  extensions  for  1485-86 
compatibility  issues  492-93 
parameters  1040, 1116 
parsing  268-69 

FILES  command  (CONFIG.SYS)  250,  789, 801-2 
File  set,  execute  command  or  program  on  a  760 
File  sharing  support,  installing  933 
File  system 

block  device  layout  of  93-103 
boot  sector  94-96 
file  allocation  table  97-101 
file  area  103 


File  system  (continued ) 

block  device  layout  (continued ) 
root  directory  101-3 
MS-DOS  kernel  54-55 
Fill  Memory 

DEBUG  F 1031-32 
SYMDEBF 1105-6 
Filter(s)  429-46 

building  431-41 
how  filters  work  430-31 
system  support  for  429-30 
used  as  child  process  441-46 
Filter  commands  729, 863, 896, 935 
Find  Character  String  (FIND)  863-64 
FIND  command  863-64 
FIND.C  program  439-41 
Find  First  File.  See  Interrupt  21H  Function  IIH; 

Interrupt  21H  Function  4EH 
Find  Next  File.  See  Interrupt  21H  Function  12H; 

Interrupt  21H  Function  4FH 

Fixed  disk 

configuring  858-62 
interleaving  90(fig.) 
layout  of  86-87 
partitions  90-92, 858 
sectors  88-89 

FDCUPP  Fixup  object  record  651, 682-93 
examples  686-93 
fixup  field  684-86 
FRAME  fixup  methods  683 
location  686 

TARGET  fixup  methods  684 
thread  field  682-84 

Flags 

display  with  DEBUG  1045-47 
maintained  by  DEBUG  1023 
maintained  by  SYMDEB 1060 
Floating-point  numbers 
display 

10-byte  1087-88 
long  (64-bit)  1083-84 
short  (32-bit)  1085-86 
enter 

10-byte  1102-03 
long  (64-bit)  1098-99 
short  (32-bit)  1100-1101 
Floppy  disk 

comparing  818-21 
copying  822-26 
layout  of  86-87 
sectors  88-89 
Flow  control  l68,  204 
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Flush  Buffer,  Read  Keyboard.  See  Interrupt  21H 
Function  OCH 
Flux  reversal  86 

Force  Duplicate  File  Handle.  See  Interrupt  21H 
Function  46H 

FOR  command  (BATCH)  66,  753,  760-6l 
Foreground  program  900 
Format  and  Verify  Track  on  Logical  Drive.  See 
Interrupt  21H  Function  44H 
Subfunction  ODH 
FORMAT  command  44, 865-71 
ASSIGN  and  741 
directory  format  281-83 
DISKCOPYand  822 
FDISKand858 
JOIN  and  877-78 

Format  Disk  Tracks.  See  Interrupt  13H  Function  05H 
FORTRAN  (language)  8, 14 
FORTRAN  Compiler,  Microsoft 
memory  models  using  137-40 
utilities  with  974,  977, 980,  987, 999 
Free  Memory  Block.  See  Interrupt  21H  Function  49H 
Frequency  modulation  (FM)  recording  86 
Function  calls.  See  System  calls 


G 

Gates,  Bill  8(fig.),  l6(fig.) 

in  the  development  of  early  BASIC  3-8, 11 
in  the  development  of  MS-DOS  14-15, 20 
General  Protection  exception.  See  Interrupt  ODH 
Generate  Cross-Reference  Listing  (CREF)  967-70 
Generic  I/O  Control  for  Block  Devices.  See  Interrupt 
21H  Function  44H  Subfunction  ODH 
Generic  I/O  Control  for  Handles.  See  Interrupt  21H 
Function  44H  Subfunction  OCH 
Get  and  Set  Time.  See  Interrupt  lAH 
Get  Assign-List  Entry.  See  Interrupt  21H  Function 
5FH  Subfunction  02H 

Get  Current  Country.  See  Interrupt  21H  Function  38H 
Get  Current  Directory.  See  Interrupt  21H 
Function  47H 

Get  Current  Disk.  See  Interrupt  21H  Function  19H 
Get  Current  Drive  Parameters.  See  Interrupt  13H 
Function  08H 

Get  Current  Video  Mode.  See  Interrupt  lOH 
Function  OFH 

Get  Date.  See  Interrupt  21H  Function  2AH 
Get  Default  Drive  Data.  See  Interrupt  21H 
Function  IBH 

Get  Device  Data.  See  Interrupt  21H  Function  44H 
Subfunction  OOH 


Get  Disk  Free  Space.  See  Interrupt  21H  Function  36H 
Get  Disk  Status.  See  Interrupt  13H  Function  OlH 
Get  Disk  Type.  See  Interrupt  13H  Function  15H 
Get  Drive  Data.  See  Interrupt  21H  Function  ICH 
Get  DTA  Address.  See  Interrupt  21H  Function  2FH 
Get  Extended  Country  Information.  See  Interrupt 
21H  Function  65H 

Get  Extended  Error  Information.  See  Interrupt  21H 
Function  59H 

Get  File  Size.  See  Interrupt  21H  Function  23H 
Get  Interrupt  Vector.  See  Interrupt  21H  Function  35H 
Get  Lead  Byte  Table.  See  Interrupt  21H  Function  63H 
Get  Logical  Drive  Map.  See  Interrupt  21H  Function 
44H  Subfunction  OEH 

Get  Machine  Name.  See  Interrupt  21H  Function  5EH 
Subfunction  OOH 

Get  MS-DOS  Version  Number.  See  Interrupt  21H 
Function  30H 

Get  Peripheral  Equipment  List.  See  Interrupt  IIH 
Get  Port  Status.  See  Interrupt  14H  Function  03H 
Get  Printer  Setup.  See  Interrupt  21H  Function  5EH 
Subfunction  03H 

Get  Printer  Status.  See  Interrupt  17H  Function  02H 
Get  Program  Segment  Prefix  Address.  See  Interrupt 
21H  Function  51H;  Interrupt  21H 
Function  62H 

Get  Return  Code  of  the  Child  Process.  See  Interrupt 
21H  Function  4DH 

Get/Set  Allocation  Strategy.  See  Interrupt  21H 
Function  58H 

Get/Set  Control-C  Check  Flag.  See  Interrupt  21H 
Function  33H 

Get/Set  Date/Time  of  File.  See  Interrupt  21H 
Function  57H 

Get/Set  File  Attributes.  See  Interrupt  21H 
Function  43H 

Get  Shift  Status.  See  Interrupt  16H  Function  02H 

Get  Time.  See  Interrupt  21H  Function  2CH 

Get/Set  Time/Date.  See  Interrupt  lAH 

Get  Usable  Memory  Size  (KB).  See  Interrupt  12H 

Get  Verify  Flag.  See  Interrupt  21H  Function  54H 

Gilbert,  Paul  5-6 

Global  descriptor  table  (GDT)  317 

Go 

DEBUG  G  584-85, 1033-34 
SYMDEB  G 1107-8 

GOTO  command  (BATCH)  67, 753, 762-63 
GRAFTABL  command  872-73 
MS-DOS  version  3  3 1445 
Graphics 

loading  character  set  872-73 
loading  screen-dump  program  874-76 
screen-display  attributes  734 
Graphics  Character  Table.  See  Interrupt  IFH 
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GRAPHICS  command  874-76 
Graphics  Device  Interface  (GDI),  Windows  529-37 
bit-block  transfers  535-36 
device  context  530 
device-context  attributes  531 
device-independent  programming  530-31 
drawing  functions  533 
mapping  modes  531-32 
metafiles  536-37 
raster  operations  for  pens  534-35 
text  and  fonts  536 
Greenberg,  Bob  8(fig.) 

GROUP  directive  (MASM),  controlling  .EXE 
programs  with  131-32 
sample  .EXE  program  using  132-37 
GRPDEF  Group  Definition  object  record  651, 680-81 


H 

Handle-type  function  calls,  for  accessing  character 
devices  150, 152-53, 155, 158,  l6l,  l63 
Hangeul  characters  37 
Hard  disk.  See  Fixed  disk 
Hardware 

breakpoints  640, 641, 642 
for  communications  170-80 
compatibility  issues,  with  MS  OS/2  489-92 
BIOS  491 
CPU  speed  491 
family  API  489-90 
linear  vs  segmented  memory  490-91 
program  timing  491 
protected  mode  489 
debugging  aids  640-42 
developers  of,  and  MS-DOS  27-29, 35-37 
MS-DOS  requirements  for 
memory  58 

microprocessor  57-58 
peripheral  devices  59 
ROM  BIOS  59-60 
Hardware  instrumentation  555-56 
Hardware  interrupts  398-400, 409-27 
categories  411-12 

characteristics  of  maskable  interrupts  412-13 
handling  maskable  interrupts  413-19 
IBM  interrupt  usage  4l0(table) 

Intel  reserved  exception  398(table), 
409-10(table) 
programming  for  419-27 

sample  replacement  handler  419-24 
supplementary  handlers  424-26 


Hardware  IRQO  (timer  tick).  See  Interrupt  08H 
Hardware  IRQl  (keyboard).  See  Interrupt  09H 
Hardware  IRQ2  (reserved).  See  Interrupt  OAH 
Hardware  IRQ3  (COM2).  See  Interrupt  OBH 
Hardware  IRQ4  (COMl).  See  Interrupt  OCH 
Hardware  IRQ5  (fixed  disk).  See  Interrupt  ODH 
Hardware  IRQ6  (floppy  disk).  See  Interrupt  OEH 
Hardware  IRQ7  (printer).  See  Interrupt  OFH 
Heads,  read/write  86, 88 
HELLO. ASM  program  357-59 

as  typical  object  module  651-54 
Help  menu  (CodeView)  1162 
Help  or  Evaluate  Expression  (SYMDEB  ?)  1152-53 
Hercules  Graphics  Card  157 
Hewlett  Packard  HP150  computer  34 
Hexadecimal  arithmetic  1035, 1109 

binary-to-hexadecimal  file  conversion 
utility  1503-5 
Hexadecimal  bytes 

displaying  contents  of  memory  as  1079-80 
entering  into  memory  1095-96 
Hexadecimal  object  file  format  1499-1505 
.HEX  files,  and  DEBUG  585-86, 1020, 1052 
/HIGH  switch,  LINK  use  of  719-21 
Hooks,  MS-DOS  53 
Hot-key  sequence  348,  382 
Huge  memory  model  139 


1 

IBMBIO.COM  20,  33,  52, 448, 774, 940 
IBM  Corporation  computers 
interrupt  usage  410(table) 

PC  (Personal  Computer)  19(fig.),  20,  21(fig.), 
26,  34(fig.) 

PC/AT  computer  39-43, 417-18 
PCjr  computer  35, 36, 37 
PC/XT  computer  30,  34(fig.) 

Personal  System/2,  MS-DOS  version  3  3 
1448 

role  in  the  development  of  MS-DOS  14-15,  26 
IBMDOS.COM  20, 447, 774, 940 
loading  52 

IBM  extended  character  set  1465-67 
IBM  Professional  Debug  Utility  641 
Idle  Interrupt.  See  Interrupt  28H 
IF  command  (BATCH)  67, 753, 764-65 
with  GOTO  762 

Include  Comment  Line  (REM)  768 

InDOS  flag  355-56 

Inference  rule,  and  MAKE  utility  1001 

Information  management  system  calls,  list  1183 
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Initialization.  See  Interrupt  14H  Function  OOH 
Initialize  Disk  (FORMAT)  865-71 
Initialize  Hard-Disk  Parameter  Table.  See  Interrupt 
13H  Function  09H 

Initialize  Port  Parameters.  See  Interrupt  14H 
Function  OOH 

Initialize  Printer.  See  Interrupt  17H  Function  OlH 
Initial  SP  value  field  (.EXE  file  header)  122 
modifying  140 
Input  from  Port 
DEBUG  1 1036 
SYMDEBIlllO 

Input/output  (I/O).  See  also  Character-device 
input/output 
input  port  1036, 1110 
output  port  1042, 1118 
redirection  67-68 
redirection  and  filters  429-30 
SYMDEB  redirection  1143-49 
INS8250  Universal  Asynchronous  Receiver 
Transmitter  (UART)  171-72 
architecture  172-79 

bit  rate  divisor  table  175(table) 
control  circuits  173, 174-77 
interrupt  enable  register  constants 
177(table) 

interrupt  identification  and  causes  178(table) 
line  control  register  bit  values  175-76(table) 
line  status  register  bit  values  177(table) 
modem  control  register  bit  values  176(table) 
port  offset  from  base  address  174(table) 
programming  interface  173-74 
receiver  172 

status  circuits  173, 177-79 
transmitter  172-73 
programming  179-80 
Insert  Lines  (EDLIN  I)  840 
Inspection-and-observation  debugging  547-49 
Install  Device  Driver  (DEVICE)  795-96 
Install  File-Sharing  Support  (SHARE)  933-34 
Instruction  sets 

8086/8088 1479-80 
80286 1480-82 
803861482-84 
Instrumentation  debugging 
external  555-72 
internal  549-55 

INT24.  ASM  critical  error  handling  program  394, 
395-98 
Intel  4004  chip  5(fig.) 

Intel  8008  chip  5(fig.) 

Intel  8080  chip  5(fig.),  10 
Intel  8086  chip  ll(fig.),  12,  58 
compatibility  issues  1507-8 


Intel  8086  chip  (continued ) 

exception  interrupts  398(table),  409-10(table) 
instruction  set  1479-80 
interrupt  priorities  411 
Intel  8088  chip  58 

compatibility  issues  1507-8 
instruction  set  1479-80 

Intel  8259A  Programmable  Interrupt  Controller  (PIC) 
349, 411, 4l4(fig.),  415, 4l6(fig.).  See  also 
Maskable  interrupts 
Intel  80186  chip  58 
Intel  80188  chip  58 
Intel  80286  chip  42(fig.),  58 

compatibility  issues  489-92 
instruction  set  1481-82 
Intel  80386  chip  42(fig.),  58 
compatibility  issues  489 
instruction  set  1483-84 
Interleaving,  disk  89-90 
Internal  disk  buffers,  configure  791-92 
Internal  stacks 

configuring  805 

at  entry  to  a  critical  error  exception  handler 
391(fig.) 

in  .EXE  programs  111-12 
performing  stack  trace  1111-12 
in  TSR  programs  353, 354-55(fig.) 
Internationalization 

MS-DOS  and  32-33, 35-37 
MS-DOS  version  2.25 1415-16 
new  national  language  support,  MS-DOS 
version  3.3 1438-48, 1451-55 
support  793 
Windows  538 
Interrupts) 

configure  internal  stacks  for  805 
daisy-chaining  handlers  557 
hardware  {see  Hardware  interrupts) 
manual  640, 641 
TSR  processing  of  hardware  349 
Interrupt  OOH,  Divide  by  Zero  398, 399, 409 
demonstration  handler  419-24 
Interrupt  OlH,  Single  Step  398,  399, 409 
Interrupt  02H,  Nonmaskable  Interrupt  (NMI)  398, 

399, 409, 411 

Interrupt  03H,  Breakpoint  Trap  400, 409 
Interrupt  04H,  Overflow  Trap  398, 400, 409 
Interrupt  05H 

IBM,  Print  Screen  410 

Intel,  BOUND  Range  Exceeded  398, 400, 409 
Interrupt  06H 

IBM,  Unused  410 

Intel,  Invalid  Opcode  398, 400, 409 
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Interrupt  07H 

IBM,  Unused  410 

Intel,  Coprocessor  Not  Available  398, 409 
Interrupt  OSH 

IBM,  Hardware  IRQO/  (Time  Tick)  382,  383, 410, 
425-26 

Intel,  Double-Fault  Exception  398, 409 
Interrupt  09H 

IBM,  Hardware  IRQl  (Keyboard)  348, 382, 410 
Intel,  Coprocessor  Segment  Overrun  398, 409 
Interrupt  OAH 

IBM,  Hardware  IRQ2  (Reserved)  410 
Intel,  Invalid  Task  State  Segment  (TSS)  398, 409 
Interrupt  OBH 

IBM,  Hardware  IRQ3  (COM2)  410 
Intel,  Segment  Not  Present  398, 409 
Interrupt  OCH 

IBM,  Hardware  IRQ4  (COMl)  410 
Intel,  Stack  Exception  398, 409 
Interrupt  ODH 

IBM,  Hardware  IRQ5  (Fixed  Disk)  410 
Intel,  General  Protection  Exception  398, 409 
Interrupt  OEH 

IBM,  Hardware  IRQ6  (Floppy  Disk)  410 
Intel,  Page  Fault  398, 409 
Interrupt  OFH 

IBM,  Hardware  IRQ7  (Printer)  410 
Intel,  Reserved  398, 410 
Interrupt  lOH 

IBM,  PC  ROM  BIOS  video  driver  159, 410, 872, 

1513- 18 

Function  OOH,  Set  Video  Mode  1513 
Function  OlH,  Set  Cursor  Size  and  Shape  1514 
Function  02H,  Set  Cursor  Position  1514 
Function  03H,  Read  Cursor  Position,  Size, 
and  Shape  1514 

Function  04H,  Read  Light-Pen  Position 

1514- 15 

Function  05H,  Select  Active  Page  1515 
Function  06H,  Scroll  Window  Up  1515 
Function  07H,  Scroll  Window  Down  1515 
Function  08H,  Read  Character  and  Attribute 
at  Cursor  1515-16 

Function  09H,  Write  Character  and  Attribute 
1516 

Function  OAH,  Write  Character  Only  1516 
Function  OBH,  Select  Color  Palette  1516 
Function  OCH,  Write  Pixel  Dot  1517 
Function  ODH,  Read  Pixel  Dot  1517 
Function  OEH,  Write  Character  as  TTY  1517 
Function  OFH,  Get  Current  Video  Mode  1517 
Function  13H,  Write  Character  String  1518 
Intel,  Coprocessor  Error  398, 410 
Interrupt  IIH,  Get  Peripheral  Equipment  List  1518 


Interrupt  12H,  Get  Usable  Memory  Size  (KB)  1519 
Interrupt  13H,  Disk  Services  1519-23 

Function  OOH,  Reset  Disk  System  1519 
Function  OlH,  Get  Disk  Status  1519-20 
Function  02H,  Read  Disk  Sectors  1520 
Function  03H,  Write  Disk  Sectors  1520 
Function  04H,  Verify  Disk  Sectors  1520 
Function  05H,  Format  Disk  Tracks  1520 
Function  08H,  Get  Current  Drive  Parameters 
1520-21 

Function  09H,  Initialize  Hard-Disk  Parameter 
Table  1521 

Function  OAH,  Read  Long  1521 
Function  OBH,  Write  Long  1521 
Function  OCH,  Seek  to  Head  1521 
Function  ODH,  Alternate  Disk  Reset  1522 
Function  lOH,  Test  for  Drive  Ready  1522 
Function  IIH,  Recalibrate  Drive  1522 
Function  14H,  Controller  Diagnostic  1522 
Function  15H,  Get  Disk  Type  1522-23 
Function  16H,  Check  for  Change  of  Floppy  Disk 
Status  1523 

Function  17H,  Set  Disk  Type  1523 
Interrupt  14H,  Serial  Port  Services  l6l,  1523-25 
debugging  and  556-57 
Function  OOH,  Initialize  Port  Parameters  222, 
1523-24 

Function  OlH,  Send  One  Character  1524 
Function  02H,  Receive  One  Character  1524 
Function  03H,  Get  Port  Status  1524-25 
Interrupt  15H,  Miscellaneous  System  Services 
1525-26 

access  to  extended  memory  functions 
3l6-17(table) 

block  move  descriptor  table  format  317(table) 
Function  02H,  Read  Data  from  Cassette  1525-26 
Function  03H,  Write  Data  to  Cassette  1526 
Function  87H,  Move  Extended  Memory  Block 
316-17 

Function  88H,  Obtain  Size  of  Extended  Memory 
3l6(table) 

Interrupt  16H,  Keyboard  Services  1526-27 
Function  OOH,  Read  Next  Character  1526 
Function  OlH,  Report  If  Character  Ready  1527 
Function  02H,  Get  Shift  Status  1527 
Interrupt  17H,  Printer  Services  1527-28 

Function  OOH,  Send  Byte  to  Printer  1527 
Function  OlH,  Initialize  Printer  1528 
Function  02H,  Get  Printer  Status  1528 
Interrupt  18H,  Transfer  Control  to  ROM-BASIC  1528 
Interrupt  19H,  Reboot  Computer  (Warm  Start)  1528 
Interrupt  lAH,  Get/Set  Time/Date  1528-30 
Function  OOH,  Read  Current  Clock  Count 
1528-29 
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Function  OlH,  Set  Current  Clock  Count  1529 
Function  02H,  Read  Real-Time  Clock  1529 
Function  03H,  Set  Real-Time  Clock  1529 
Function  04H,  Read  Date  from  Real-Time  Clock 
1529-30 

Function  05H,  Set  Date  in  Real-Time  Clock  1530 
Function  06H,  Set  Alarm  1530 
Function  07H,  Reset  Alarm  (Turn  Alarm  Off) 
1530 

Interrupt  IBH,  Control-Break  (user  defined)  387-89, 
410 

Interrupt  ICH,  Timer  Tick  (user  defined)  410 
Interrupt  IDH,  Video  Parameter  Pointer  410 
Interrupt  lEH,  Disk  Parameter  Pointer  410 
Interrupt  IFH,  Graphics  Character  Table  872-73 
Interrupt  20H,  Terminate  Program  63, 108, 1185-86 
terminating  .EXE  programs  117, 118 
Interrupt  21H,  MS-DOS  system  calls  63, 110, 1050 
for  accessing  directories  284-86(table) 
compatibility,  with  MS  OS/2  493-94 
error  information  401, 402 
for  file  and  record  management  248(table) 
Function  OOH,  Terminate  Process  1187-88 
Function  OlH,  Character  Input  with  Echo  154, 
1189-90 

Function  02H,  Character  Output  158, 1191-92 
Function  03H,  Auxiliary  Input  l6l,  l69, 1193-94 
Function  04H,  Auxiliary  Output  l6l,  1195-96 
Function  05H,  Print  Character  163, 1197-98 
Function  06H,  Direct  Console  I/O  154, 158, 
1199-1200 

Function  07H,  Unfiltered  Character  Input 
Without  Echo  154, 1201-2 
Function  08H,  Character  Input  Without  Echo 
154, 169, 1203-4 

Function  09H,  Display  String  158, 1205-6 
Function  OAH,  Buffered  Keyboard  Input  154, 
155, 1207-8 

Function  OBH,  Check  Keyboard  Status  154, 155, 
169, 1209-10 

Function  OCH,  Flush  Buffer,  Read  Keyboard  154, 
155, 1211-12 

Function  ODH,  Disk  Reset  1213-14 
Function  OEH,  Select  Disk  1215-16 
Function  OFH,  Open  File  with  FCB  270, 

1217-19 

Function  lOH,  Close  File  with  FCB  271, 1220-21 
Function  IIH,  Find  First  File  277,  286,  287, 
1222-24 

Function  12H,  Find  Next  File  286,  287, 1225-26 
Function  13H,  Delete  File  276-77, 1227-28 
Function  14H,  Sequential  Read  272, 1229-30 
Function  15H,  Sequential  Write  272, 1231-32 
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Function  16H,  Create  File  with  FCB  156,  269, 
1233-34 

Function  17H,  Rename  File  275, 287, 1235-36 
Function  19H,  Get  Current  Disk  1237 
Function  lAH,  Set  DTA  Address  268, 353, 
1238-39 

Function  IBH,  Get  Default  Drive  Data  1240-41 
Function  ICH,  Get  Drive  Data  1242-44 
Function  21H,  Random  Read  272, 1245—46 
Function  22H,  Random  Write  273, 1247-48 
Function  23H,  Get  File  Size  277, 1249-50 
Function  24H,  Set  Relative  Record  1251-52 
Function  25H,  Set  Interrupt  Vector  352, 419, 
1253-54 

Function  26H,  Create  New  Program  Segment 
Prefix  1255-56 

Function  27H,  Random  Block  Read  273, 

1257-59 

Function  28H,  Random  Block  Write  273-75, 
1260-62 

Function  29H,  Parse  Filename  268, 1263-65 
Function  2AH,  Get  Date  1266-67 
Function  2BH,  Set  Date  1268-69 
Function  2CH,  Get  Time  1270-71 
Function  2DH,  Set  Time  1272-73 
Function  2EH,  Set/Reset  Verify  Flag  1274-75 
Function  2FH,  Get  DTA  Address  268, 353, 1276 
Function  30H,  Get  MS-DOS  Version  Number 
1277-78 

Function  31H,  Terminate  and  Stay  Resident  351, 
381, 1279-80  (see  also  Terminate-and- 
stay-resident  utilities) 

Function  33H,  Get/Set  Control-C  Check  Flag 
1281-82 

Function  34H,  Return  Address  of  InDOS  Flag 
355-56, 1283 

Function  35H,  Get  Interrupt  Vector  307, 315,  352, 
419, 1284 

Function  36H,  Get  Disk  Free  Space  1285-86 
Function  38H,  Get/Set  Current  Country  793, 

1451 

Get  Current  Country  1287-89 
Set  Current  Country  1290 
Function  39H,  Create  Directory  287, 1291-92 
Function  3AH,  Remove  Directory  287, 1293-94 
Function  3BH,  Change  Current  Directory  281, 
288, 1295-96 

Function  3CH,  Create  File  with  Handle  251,  287, 
1297-99 

Function  3DH,  Open  File  with  Handle  155, 158, 
161, 163, 253, 282, 307, 315, 1300-1303 
Function  3EH,  Close  File  255, 307, 1304-5 
Function  3FH,  Read  File  or  Device  154, 155,  l6l, 
256, 431, 1306-7 
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Function  40H,  Write  File  or  Device  158,  l6l,  163, 
256, 431, 1308-9 

Function  41H,  Delete  File  260,  287, 1310-11 
Function  42H,  Move  File  Pointer  258, 1312-14 
Function  43H,  Get/Set  File  Attributes  261-62, 
287, 1315-16 

Function  44H,  lOCTL  164-66, 203, 315, 

1317-18 

extended  MS-DOS  version  3  3 1455-58 
Subfunction  OOH,  Get  Device  Data  164,  l65, 
307, 1319-21 

Subfunction  OlH,  Set  Device  Data  l64,  l65, 
1322-23 

Subfunction  02H,  Receive  Control  Data  from 
Character  Device  164-65, 1324-25 
Subfunction  03H,  Send  Control  Data  to 
Character  Device  165, 1324-25 
Subfunction  04H,  Receive  Control  Data  from 
Block  Device  1326-28 
Subfunction  05H,  Send  Control  Data  to 
Block  Device  1326-28 
Subfunction  06H,  Check  Input  Status  155, 
165, 1329-30 

Subfunction  07H,  Check  Output  Status  l65, 
1329-30 

Subfunction  08H,  Check  If  Block  Device  Is 
Removable  1331-32 

Subfunction  09H,  Check  If  Block  Device  Is 
Remote  1333-34 

Subfunction  OAH,  Check  If  Handle  Is 
Remote  165, 1335-36 
Subfunction  OBH,  Change  Sharing  Retry 
Count  1337-38 

Subfunction  OCH,  Generic  I/O  Control  for 
Handles  l65, 1339-40, 1455-58 
Subfunction  ODH,  Generic  I/O  Control  for 
Block  Devices  1341-42 
Subfunction  ODH,  minor  code  40H,  Set 
Device  Parameters  1343-46 
Subfunction  ODH,  minor  code  41H,  Write 
Track  on  Logical  Drive  1350-51 
Subfunction  ODH,  minor  code  42H,  Format 
and  Verify  Track  on  Logical  Drive 
1352-53 

Subfunction  ODH,  minor  code  60H,  Get 
Device  Parameters  1347-49 
Subfunction  ODH,  minor  code  6lH,  Read 
Track  on  Logical  Drive  1350-51 
Subfunction  ODH,  minor  code  62H,  Verify 
Track  on  Logical  Drive  1352-53 
Subfunction  OEH,  Get  Logical  Drive  Map 
1354-55 
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Function  44H,  lOCTL  (continued) 

Subfunction  OFH,  Set  Logical  Drive  Map 
1354-55 

Function  45H,  Duplicate  File  Handle  67,  262, 
1356-57 

Function  46H,  Force  Duplicate  File  Handle  67, 
263, 1358-59 

Function  47H,  Get  Current  Directory  288, 
1360-61 

Function  48H,  Allocate  Memory  Block  299, 303, 
352, 1362-63 

Function  49H,  Free  Memory  Block  299, 303, 352, 
1364-65 

Function  4AH,  Resize  Memory  Block  299, 323, 
1366-67 

Function  4BH,  Load  and  Execute  Program 
(EXEC)  64, 718, 1368-74.  isee  also 
EXEC  function) 

Function  4CH,  Terminate  Process  with  Return 
Code  115-17, 144, 1375-76 

Function  4DH,  Get  Return  Code  of  Child 
Process  328, 1377-78 

Function  4EH,  Find  First  File  285,  286, 287, 
288-90, 1379-81 

Function  4FH,  Find  Next  File  285,  286, 287, 
288-90, 1382-84 

Function  50H,  Set  Program  Segment  Prefix 
Address  352, 383 

Function  51H,  Get  Program  Segment  Prefix 
Address  352, 383 

Function  54H,  Get  Verify  Flag  1385 

Function  56H,  Rename  File  260,  287, 1386-87 

Function  57H,  Get/Set  Date/Time  of  File  262, 
265,  287, 1388-90 

Function  58H,  Get/Set  Allocation  Strategy 
1391-92 

Function  59H,  Get  Extended  Error  Information 
269, 327, 383-84, 1393-96 
and  newer  system  calls  406-8 
and  older  system  calls  405-6 

Function  5AH,  Create  Temporary  File  251,  252, 
1397-98 

Function  5BH,  Create  New  File  251,  252, 
1399-1400 

Function  5CH,  Lock/Unlock  File  Region 
1401-3 

Function  5DH,  Set  Extended  Error  Information 
352 

Function  5EH,  Network  Machine  Name/Printer 
Setup 

Subfunction  OOH,  Get  Machine  Name  1404 
Subfunction  02H,  Set  Printer  Setup  1405-6 
Subfunction  03H,  Get  Printer  Setup  1405-6 
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Interrupt  21H  (continued) 

Function  5FH,  Get/Make  Assign-List  Entry 

Subfunction  02H,  Get  Assign-List  Entry 
1407-8 

Subfunction  03H,  Make  Assign-List  Entry 
1409-10 

Subfunction  04H,  Cancel  Assign-List  Entry 
1411-12 

Function  62H,  Get  Program  Segment  Prefix 
Address  1413-14 

Function  63H,  Get  Lead  Byte  Table  1415-16 
Function  65H,  Get  Extended  Country 
Information  1451-54 
Function  66H,  Select  Code  Page  1454-55 
Function  67H,  Set  Handle  Count  1448-50 
Function  68H,  Commit  File  1448, 1450-51 
for  terminate-and-stay-resident  programs 
350-53 

Interrupt  22H,  Terminate  Routine  Address  63,  HO, 
1417 

Interrupt  23H,  Control-C  Handler  Address  63, 110, 
386-89, 1418 

Interrupt  24H,  Critical  Error  Handler  Address  63,  HO, 
354, 390-98, 1419-21 
MS-DOS  versions  2.0  and  later  402-3 
Interrupt  25H,  Absolute  Disk  Read  63, 1422-23 
Interrupt  26H,  Absolute  Disk  Write  63, 1424-25 
Interrupt  27H,  Terminate  and  Stay  Resident  63, 266, 
351, 1426-27.  See  also  Terminate-and- 
stay-resident  utilities 
Interrupt  28H,  Idle  Interrupt  63,  266,  353 
Interrupt  2FH,  Multiplex  Interrupt  63, 356-57, 381, 
1428-29 
Interrupt  30H  63 
Interrupt  60H  565, 600 
Interrupt  67H  306,  307,  309, 315 
Interrupt  enable  register  constants,  INS8250  UART 
chip  177(table) 

Interrupt  identification  and  causes,  INS8250  UART 
chip  178(table) 

Interrupt  request  lines  (IRQ)  414, 416-19 
l6-level  designs  417-19 
cascade  effect  417, 4l8(fig.) 
eight-level  designs  4l7(table) 

Interrupt  routine  (Jntr),  device  driver  453-68 

Build  BIOS  Parameter  Block  function  459-60 
command-code  functions  454-55 
Device  Open/Close  functions  464-65 
Flush  Input/Output  Buffer  functions  463-64 
Generic  lOCTL  function  466 
Get/Set  Logical  Device  functions  467-68 
Init  (Initialization)  function  455-57 
Input/Output  Status  functions  463 
lOCTL  Read/Write  functions  464 


Interrupt  routine  (continued ) 

Media  Check  function  457-59 
Nondestructive  Read  function  462 
Output  Until  Busy  function  466 
Read,  Write,  and  Write  with  Verify  functions 
461-62 

Removable  Media  function  465-66 
Interrupt  service  routine  (ISR)  180,  203-4, 412 
in  COMDVR.  ASM  196-98, 203-4 
hardware  module  215-22 
Interrupt  vector  functions,  in  TSR  programs  352 
Interrupt  vector  table  58 

in  conventional  memory  297-98 
initializing  69, 70(fig.) 

Invalid  Opcode  exception.  See  Interrupt  06H 
Invalid  Task  State  Segment  (TSS)  exception.  See 
Interrupt  OAH 

lOCTL.  See  Interrupt  21H  Function  44H 
IO.SYS  33, 448, 774, 940 
BIOS  and  61-62 
loading  52, 72(fig.) 
modules  73 

ISO  Open  System  Interconnect  42 
ISR.  See  Interrupt  service  routine 


J 

JOIN  command  877-78 
ASSIGN  and  741 
BACKUP  and  747 
CHKDSKand775 
DISKCOMPand818 
DISKCOPYand822 
FORMAT  and  866 
MKDIR/MDand885 
Join  Disk  to  Directory  (JOIN)  877-78 
Jump  to  Label  (GOTO)  762-63 


K 

Kanji  characters  37(fig.) 

Kernel.  See  MS-DOS  kernel 
KEYB  command  1440-41 
Keyboard  154-57 

ANSI.SYS  key  and  extended  key  codes  1471-72 

character  input  functions  154(table) 

defining  879, 1440-41 

redefining  to  a  specific  string  734-36 

sample  input  programs  156-57 

TSR  input  isee  Hot-key  sequence) 
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Subject 


Keyboard  (KEYB)  1440-41 
Keyboard  Services.  See  Interrupt  16H 
KEYBatjc  command  879-81 
Key  commands  (CodeView)  ll63 
Kildall,  Gary  10 


Loop  or  Subroutine,  Proceed  Through  1043 
LPTl  (first  parallel  printer  port)  151, 163 
LPT2  (second  parallel  printer  port)  151, 163 
LPT3  (third  parallel  printer  port)  151, 163 


L 

Label(s) 

displaying  volume  954 

jumping  to  batch-file  line  following  specified 
label  762-63 
modify  volume  882 
LABEL  command  882-84 
ASSIGN  and  741 
Lane,  Jim  8(fig.) 

Language  menu  (CodeView)  1161-62 
Large  memory  model  139 
LASTDRIVE  command  (CONFIG.SYS)  789, 803 
LC.  ASM  lowercase  filter  program  437-39 
LEDATA  Logical  Enumerated  Data  object  record  651, 
694-95 
Letwin,  Gordon  8(fig.) 

Lewis,  Andrea  8(fig.) 

Library  Manager.  See  LIB  utility 
LIB  utility  701-2, 980-86 
LIDATA  Logical  Iterated  Data  object  record  651, 
696-97 

Lifeboat  Associates  12, 27 

Line  control  register  bit  values  175(table) 

Line  Editor  (EDLIN)  829-31 

Line  number,  defined  1058 

Line  Status  Register  bit  values  177(table) 

LINK.  See  Object  Linker 

LINNUM  Line  Number  object  record  651, 672-73 
List  Breakpoints  (SYMDEB  BL)  1071 
List  Lines  (EDLIN  L)  841 

LNAMES  List  of  Names  object  record  651, 674-75 
Load  and  Execute  Program.  See  EXEC  function; 

Interrupt  21H  Function  4BH 
Loader,  operating  system  52, 72 
Load  File  or  Sectors 
DEBUG  L 1037-38 
SYMDEB  L 1113-14 

Load  Graphics  Character  Set  (GRAFTABL)  872-73 
Load  Graphics  Screen-Dump  Program  (GRAPHICS) 
874-76 

Loading  MS-DOS  68-83 

COMMAND.COM  shell  76-83 
ROM  BIOS,  POST  and  bootstrapping  68-72 
system  initialization  73-76 
Lock/Unlock  File  Region  1401-3 


M 

McDonald,  Marc  8  (fig.),  9 

Machine  Code  Display  Mode,  Enable  1129 

Machine  language 

assembling  1024, 1063 
disassembling  programs  in  1051, 1132 
Macro(s),  in  MAKE  utility  1000-1001 
Macro  Assembler,  Microsoft  See  Microsoft  Macro 
Assembler 

Maintain  Programs  (MAKE)  999-1003 
Make  Assign-List  Entry  1409-10 
Make  Directory  (MKDIR  or  MD)  885-86 
MAKE  utility  999-1003 

Map  files,  processed  to  create  symbol  files  1004 
MAPSYM  utility  593, 1004-6 
MARK  condition  172 
Maskable  interrupts  412-19 
characteristics  of  412-13 
general  interrupt  sequence  4l3(fig.) 
handling  413-19 

8259A  Programmable  Interrupt  Controller 
(PIC)415,4l6(fig.) 

IRQ  levels  416-19 

MASM.  See  Microsoft  Macro  Assembler 
MAXALLOC  field  121, 124, 322 
.EXE  memory  300-301 
modifying  140 
MCOPY  program  956-57 
MD  command.  See  MKDIR/MD  command 
M-DOS,  development  of  8-9, 12, 15-19 
Medium  memory  model  138 
Memory  297-319 

allocated  to  .COM  and  .EXE  programs  142, 
300-305 

comparing  areas  of  1026, 1074 

conventional  isee  Conventional  memory) 

displaying  1027, 1075-90 

entering  data  into  1029, 1091-1104 

expanded  {see  Expanded  memory) 

extended  isee  Extended  memory) 

filling  1031, 1105 

linear  vs  segmented  490-91 

making  available  with  EXEC  323, 336-37 

management 

with  MS-DOS  kernel  53-54 

with  Windows  510-11 
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Memory  (continued ) 

moving  area  contents  1039 
MS-DOS  requirements  58 
preallocated,  in  .EXE  programs  112-13 
searching  1048, 1125 
segments  isee  Memory  segments) 
system  calls  for  1184 

transient  use  of,  by  COMMAND.COM  24 
TSR  RAM  management  351-52 
virtual  disk  in  907 
Memory  arena  298 

Memory-image  files,  converting  .EXE  files  to  971 
Memory  models,  for  .EXE  programs  137-40 
MEMORY  parameter  128 
Memory  segments 

absolute  segments  647 
alignment  of  647, 708-9 
classes  of  707-8 
concatenated  segments  647-48 
creating  values  490-91 
DGROUP  718-21 
fixups  648, 649(fig.) 
frames  646 

groups  for  unified  addressing  714 
groups  of  segments  648-49, 709 
vs  linear  memory  490 
logical  segments  646 
order  and  combinations  707-9 
overlays  715-18 
relocatable  segments 
TSR  programs  713-14 
uninitialized  data  714-15 
Memory  Size.  See  Interrupt  12H 
MEMO.TXT  program  252 
Messaging  system,  Windows  522-29 
Metafiles  (Windows) 

Micro  Instrumentation  Telemetry  Systems  (MITS)  4, 
7(fig.) 

Microprocessor,  MS-DOS  requirements  for  57-58.  See 
also  specific  chips 
Microsoft  Corporation 

8086  chip  technology  and  11-13 
BASIC  development  3-8, 14 
competition  with  CP/M  9-10,  27-29 
M-DOS  development  8-9, 15-19 
MS-DOS  isee  Development  of  MS-DOS;  MS-DOS 
operating  system;  MS-DOS  versions  1.x 
throughwersion  3.3) 

OS/2  CseeMS  OS/2) 
personnel  in  1978  8(fig.) 

Microsoft  Macro  Assembler  (MASM) 
description  1007-11 
messages  1012-19 

sample  program  structuring  with  SEGMENT 
and  GROUP  132-36 


Microsoft  Macro  Assembler  (continued ) 

using  GROUP  to  control  .EXE  programs  131-32 
using  SEGMENT  to  control  .EXE  programs 
125-37 

utilities  with  967,  974, 977, 980, 987, 1004, 

1054, 1157 

Microsoft  Networks  43-44, 933.  See  also  Networking 
Microsoft  Object  Linker  (LINK).  See  Object  Linker 
Microsoft  Windows.  See  Windows 
MINALLOC  field  121, 124 
.EXE  memory  300 
modifying  140 

Miscellaneous  System  Services.  See  Interrupt  15H 
Mitsubishi  Corporation  35 
MKDIR/MD  command  885-86 
Mode(s),  real  vs  protected  operating  58, 316 
MODE  command  887 

AUTOEXEC.BAT  and  755, 887 
code-page  options  1446-47 
display  890-91 

MS-DOS  version  3.3 1438, 1446-47 
printer  888-89 
redirect  printing  894-95 
serial  port  892-93 
Modem  170-71 

Modem  Control  Register  bit  values  176(table) 

Modem  engine  168, 206-9 
code  207-8 

implementing  with  MS-DOS  functions  168-70 
Modem  Status  Register  bit  values  178(table) 
MODEND  Module  End  object  record  651, 661-62 
Modified  frequency  modulation  (MEM)  86 
Modify  .EXE  File  Header  (EXEMOD)  974-76 
Modify  Volume  Label  (LABEL)  882-84 
MODULE- A  program  132-34 
MODULE_B  program  134-35 
MODULE_C  program  135-36 
Monochrome  Display  Adapter  (MDA)  157 
MORE  command  896 
Move  (Copy)  Data 
DEBUG  M 1039 
SYMDEBM1115 

Move  Extended  Memory  Block.  See  Interrupt  15H 
Function  87H 

Move  File  Pointer.  See  Interrupt  21H  Function  42H 

Move  Lines  (EDLIN  M)  842-43 

MS-DOS  Executive  (Windows)  505-6(fig.) 

MS-DOS  kernel  53-55, 62-63, 447.  See  also 
MSDOS.SYS 
file  system  54-55 
initializing  73, 74 
memory  management  53-54 
peripheral  support  54 
process  control  53 


Indexes  1553 


Subject 


MS-DOS  operating  system  51-60.  See  also  BIOS; 

COMMAND.COM;  MS-DOS  kernel 
basic  character  devices  151-64 
basic  requirements  for  57-60 
compatibility  with  OS/2  489-97 
hardware  issues  489-92 
operating-system  issues  492-97 
development  of  {see  Development  of  MS-DOS) 
displaying  version  952 
loading  68-83 
major  elements  of  61-68 
system  components  52-57 
system  initialization  isee  SYSINIT) 
three  operating  system  types  51(table) 
user  interface  55  (.see  also  COMMAND.COM; 
SHELL  comand) 

versions  55-57.  See  also  names  of  individual 
versions,  e.g.,  MS-DOS  versions  1.x 
MSDOS.SYS  62, 447,  774, 940.  See  also  MS-DOS 
kernel 

loading  52, 72(fig.) 

moving  to  begin  initialization  73, 74(fig.) 
MS-DOS  system  calls.  See  System  calls,  MS-DOS 
MS-DOS  versions  1.x 

development  of  20-29 
MS-DOS  versions  2.x 

development  of  30-38 

internal  stack  use  in  TSR  programs  353, 354-55 
MS-DOS  version  3.0 

development  of  39-44 
extended  error  information  401-8 
internal  stack  use  in  TSR  programs  343, 354-55 
MS-DOS  version  31 

development  of  43-44 
extended  error  information  401-8 
MS-DOS  version  3.2 
development  of  44 
extended  error  information  401-8 
MS-DOS  version  3-3 1433-59 
critical  error  handling  390 
new  national  language  support  1438-48 
programming  considerations  1448-58 
extension  of  lOCTL  1455-58 
file  management  1448-51 
internationalization  support  1451-55 
MS-DOS  partitions  extension  1458 
user  considerations  1433-48 
batch-file  processing  1434-35 
enhanced  commands  1436-38 
FASTOPEN  command  1433-34 
PC-DOS  commands  1435-36 


MS  OS/2  operating  system,  programming  for 
compatibility  489-97 
hardware  489-92 
operating-system  issues  492-97 
Multi-Color  Graphics  Array  (MCGA)  157 
Multiplex  Interrupt.  See  Interrupt  2FH 
Multitasking  53 

compatibility  issues  in  496-97 
Windows  529 

MYFILE.DAT  program  257-58,  274-75 


Name  File  or  Command-Tail  Parameters 
DEBUG  N 1040-41, 1052 
SYMDEB  N 1116-17 

National  language  support,  MS-DOS  version  3  3 
1438-48.  See  also  COUNTRY 
command 

code  pages  and  code-page  switching  1438-39 
for  EGA-only  systems  1447 
for  PS/2  and  printer  1448 
modified  support  commands  1442-47 
new  support  commands  1440-42 
system  files  1439 

National  Language  Support  Function  (NLSFUNC) 
command,  MS-DOS  1441-42 
Network  Adapter  card,  IBM  42, 43 
Networking 

installing  file-sharing  support  933 
MS-DOS  versions  3.x  35, 39-44 
Network  Machine  Name/Printer  Setup.  See  Interrupt 
21H  Function  5EH 

New  Executable  file  header  format  1487-97 
code  and  data  segment  1495-97 
entry  table  1493-94 
imported  names  table  1493 
module  reference  table  1493 
nonresident  names  tables  1494-95 
2^5  old  1487 

resident  names  table  1492-93 
resource  table  1491-92 
segment  table  1490 
Nishi,  Kay  14-15 
NLSFUNC  command  1441-42 
Nonmaskable  interrupt  (NMI)  399, 411, 640.  See  also 
Interrupt  02H 

NOTEPAD  display  (Windows)  501-4(fig.) 

NUL  device  59,151 
andCTTY810 
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OBJDUMP.C  program  1509-12 
Object  files  701-2 

hexadecimal  files  format  1499-1505 
Object  Linker  (LINK)  701-21, 757, 981, 993-98, 1004 
building  a  .EXE  file  header  712(table) 
combine  parameters  127-28 
converting  .EXE  files  produced  by,  with 
EXE2BIN  971-73 
creating  .EXE  files  620- 21 
creating  map  files  with  1004 
description  of  988-92 
environmental  variables  in  931 
functions  of  703 
LINK  intervals  709-12 
messages  993-98 

object  files,  object  libraries,  and  LIB  701-2 
object  module  order  703-6 
operating  in  .EXE  program  111,  113 
organizing  memory  with  713-21 
return  codes  992-93 
segment  order/combinations  707-9 
Object  module(s)  643-700 
contents  of  645-46 
dump  utility  1509-12 
linking  isee  Object  Linker) 
object  record  formats  655-56 
object  records  listed  657-700 
order  of  703 -6 
structure  of  650-55 

object  record  order  651 
references  between  records  654-55 
terminology  646-49 
translation  of  assembly  programs  into 

relocatable  isee  Microsoft  Macro 
Assembler) 
types  of  650, 651(fig.) 
typical  651-54 
use  of  643-44 

Object  module  library  file  701-2 
creating/modifying  980-86 
Object  records 

formats  655-56 
listed  657-700 
order  651 

references  between  654-55 
types  650, 651(fig.) 

Obtain  Size  of  Extended  Memory.  See  Interrupt  15H 
Function  88H 

OFFSET  operator  (MASM),  using  on  labels  in 
grouped  segments  131-32 


Open  File  with  FCB.  See  Interrupt  21H  Function  OFH 
Open  File  with  Handle.  See  Interrupt  21H 
.  Function  3DH 
Open-loop  servomechanism  89 
Open  Symbol  Map  (SYMDEB  XO)  1140 
Operating  system 

compatibility  issues,  MS-DOS  and  MS  OS/2 
492-97 

error  codes  495 
filenames  492-93 
MS-DOS  function  calls  493-94 
multitasking  concerns  496-97 
seeks  495 

in  conventional  memory  298 
three  types  of  51(table),  52 
transfer  940 

Operating-system  loader  52, 72 
Options  menu  (CodeView)  ll6l 
O’Rear,  Bob  8(fig.),  15-19 
OS/2  operating  system.  See  MS  OS/2  operating 
system 

Output  to  Port 

DEBUG  0 1042 
SYMDEB  01118 

Overflow  Trap  exception.  See  Interrupt  04H 
OVERLAY.  ASM  program  342 
Overlays,  program  122-23 

EXEC  function  and  321,  322-23, 335-43 
example  program  337-42 
loading  and  executing  336-37 
making  memory  available  335-36 
preparing  parameters  336-37 
LINK  memory  organization  using  715-18 


P 

PAGE  alignment  126-27 
Page  Fault  exception.  See  Interrupt  OEH 
Fanners,  Nancy  34 
PARA  alignment  126 
Parallel  port,  input/output  163 
PARENT.  ASM  program  330-34 
Parent  program,  use  of  EXEC  by  321 
sample  program  330-36 
Parity  parameters  892 

Parse  Filename.  See  Interrupt  21H  Function  29H 
Partition(s) 

block  device  90-92, 858 
extended,  in  MS-DOS  version  3.3 1458 
Partition  table  91,  92 
Pascal  (language)  14 
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Pascal  Compiler,  Microsoft,  utilities  with  974, 977, 
980, 987, 1157 
Paterson,  Tim  6, 12-13,  l6 
PATH  commmand  739, 897-98 
AUTOEXEC.BAT  and  65,  755 
COMMAND.COM  and  65,  783 
SET  and  930, 931 
PATH  variable  930 

PAUSE  command  (BATCH)  67,  753,,  766-67 
PC-DOS  xix,  27,  55-57,  725 

basic  character  devices  151-64 
commands  from,  included  in  MS-DOS  version 
3.31435-36 

commands  only  in  725, 785, 925, 948 
loading  52 

memory  requirements  58 
versions  55-57 

PC  Probe  hardware  debugging  aid  641 
PC  ROM  BIOS  function  calls  1513-30.  See  also 
Interrupt  lOH  through  lAH 
Perform  Conditional  Execution  (IF)  764-65 
Perform  Hexadecimal  Arithmetic 
DEBUG  H 1035 
SYMDEB  H 1109 

Perform  Stack  Trace  (SYMDEB  K)  1111-12 
Peripheral  devices  supported  by  MS-DOS  59 
Peripheral  support,  with  MS-DOS  kernel  54 
Periscope  hardware  debugging  aid  641 
Peters,  Chris  33-34,  39 
PIFEDIT  (Windows)  507 
Pipes  53 

I/O  redirection  through  67 
POST  (power-on  self  test),  and  loading  MS-DOS 
68-72 

Print  Character.  See  Interrupt  21H  Function  05H 
PRINT  command  33, 899-903 
ASSIGN  and  741 
Printer.  See  also  PRN 
configuring  888 
input/output  163-64 
redirecting  output  894-95 
Printer  Services.  See  Interrupt  17H 
Print  Screen.  See  Interrupt  05H 
Print  Spooler  (PRINT)  899-903 
development  in  MS-DOS  33 
PRN  (printer  output)  22,  59, 62, 151, 163-64.  See  also 
LPTl;  LPT2;  LPT3 
CTTYand810 
filters  and  429 
opening  76 


Proceed  Through  Loop  or  Subroutine 
DEBUG  P 1043 
SYMDEB  P 1119-20 

Process  control,  with  MS-DOS  kernel  53 
Process  management  system  calls  1183 
Program(s).  See  also  .COM  program  files;  .EXE 
program  files 

assembling  machine  instructions  for  1024 
crash  protection  for  640 
debugger  1020-23 
disassembling  1051 
go  execute  1033, 1107 
loading  (^see  EXEC  function) 
overlays  {.see  Overlays,  program) 
timing  of  491 

trace  execution  of  1050, 1130-31 
Program  Debugger  (DEBUG)  1020-23.  See  also 

Debugging  in  MS-DOS;  DEBUG  utility 
Program  Information  File  (PIF)  500 
Programmable  Interrupt  Controller.  See  Intel  8259A 
Programmable  Interrupt  Controller 
(PIC);  Maskable  interrupts 
Program  segment(s) 

controlling  .EXE  programs  with  MASM  GROUP 
131-32 

controlling  .EXE  programs  with  MASM 
SEGMENT  125-30 
size  reduction  of  130 
Program  segment  prefix  (PSP)  1020 
.EXE  programs  108-11 
file  control  block  functions  and  267-68 
get/set  address  functions  in  TSR  programs  352 
inserting  filenames/switches  into 
simulated  1040 
structure  1477 

warm  boot/terminate  vector  117-18 
PROMPT  command  904-6 

AUTOEXEC.BAT  and  65,  755 
COMMAND.COM  and  65, 783 
escape  sequences  in  732 
SET  and  931 
Protected  mode 

compatibility  issues  489 
vs  real  mode  58,  316 

PROTOC.  ASM  character  filter  program  431-33 
PROTOC.C  character  filter  program  433 
PROTOL.  ASM  line  filter  program  434-35 
PROTOL.C  line  filter  program  436 
p-System  operating  system  26 
PUBDEF  Public  Names  Definition  object  record  651, 
669-71 

PUBLIC  parameter  127 
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QDOS  operating  system  12, 27 
QuickBASIC  programs  550-55,  567-69, 
1503-5 

Quit  DEBUG  (DEBUG  Q)  1044 
Quit  EDLIN  (EDLIN  Q)  845 
Quit  SYMDEB  (SYMDEB  Q)  1121 


R 

RAMciisk86 
RAMDRIVE.SYS  907-9 

Random  Block  Read.  See  Interrupt  21H  Function  27H 
Random  Block  Write.  See  Interrupt  21H  Function  28H 
Random  Read.  See  Interrupt  21H  Function  21H 
Random  Write.  See  Interrupt  21H  Function  22H 
Range,  defined  1058 

Raster  operation  codes  (Windows)  534,  535-36 
Raw  versus  cooked  mode  153-54 
RD  command.  See  RMDIR/RD  command 
Read  Character  and  Attribute  at  Cursor.  See  Interrupt 
lOH  Function  08H 

Read  Current  Clock  Count.  See  Interrupt  lAH 
Function  OOH 

Read  Cursor  Position,  Size,  and  Shape.  See  Interrupt 
lOH  Function  03H 

Read  Data  from  Cassette.  See  Interrupt  15H 
Function  02H 

Read  Date  from  Real-Time  Clock.  See  Interrupt  lAH 
Function  04H 

Read  Disk  Sectors.  See  Interrupt  13H  Function  02H 
Read  File  or  Device.  See  Interrupt  21H  Function  3FH 
Read  Light-Pen  Position.  See  Interrupt  lOH 
Function  04H 

Read  Long.  See  Interrupt  13H  Function  OAH 
Read  Next  Character.  See  Interrupt  16H  Function  OOH 
Read  Pixel  Dot.  See  Interrupt  lOH  Function  ODH 
Read  Real-Time  Clock.  See  Interrupt  LAH 
Function  02H 

Read  Track  on  Logical  Drive,  See  Interrupt  21H 
Function  44H  Subfunction  ODH 
Read/write  multiple  sectors  24 
Real  mode  58,  316 

Reboot  Computer  (Warm  Start).  See  Interrupt  19H 
Recalibrate  Drive.  See  Interrupt  13H  Function  IIH 
Receive  Control  Data  from  Block  Device.  See 
Interrupt  21H  Function  44H 
Subfunction  04H 

Receive  Control  Data  from  Character  Device.  See 
Interrupt  21H  Function  44H 
Subfunction  02H 


Receive  One  Character.  See  Interrupt  14H 
Function  02H 
RECOVER  command  910-11 
Recover  Files  (RECOVER)  910-11 
Redirectable  I/O,  and  filter  operation  429-30 
Redirect  Printing  (MODE)  894-95 
Redirect  SYMDEB  Input  (SYMDEB  <)  1143-44 
Redirect  SYMDEB  Input  and  Output 
(SYMDEB  =)  1146 

Redirect  SYMDEB  Output  (SYMDEB  >)  1145 
Redirect  Target  Program  Input  (SYMDEB  {)  1147 
Redirect  Target  Program  Input  and  Output 
(SYMDEB  ~)  1149 

Redirect  Target  Program  Output  (Symdeb })  1148 
Registers 

AX-extended  error  code,  MS-DOS  version  3-3 
1461-62 

BH-error  class,  MS-DOS  version  3  3 1462 

BL-suggested  action,  MS-DOS  version  3.3 1463 

child  program  execution  328- 

CH-locus,  MS-DOS  version  3.3 1463 

critical  error  handling  394-98 

DEBUG  initialization  582 

displaying  or  modifying  1045, 1122 

.EXE  program  settings  113-15 

expanded  memory  310-12 

extended  error  information  401-2, 404-5 

extended  memory  316-19 

INS8250  UART  chip  171-80 

maintained  by  DEBUG  1022 

maintained  by  SYMDEB  IO6O-6I 

overlay  execution  337 

PC  1045 

Relocation  pointer  table,  in  .EXE  file  headers  123 
REM  command  (BATCH)  67,  753,  768 
Remove  Directory.  See  Interrupt  21H  Function  3AH 
Remove  Directory  (RMDIR  or  RD)  923-24 
Rename  File  (RENAME  or  REN).  See  Interrupt  21H 
Function  17H;  Interrupt  21H 
Function  56H 

RENAME/REN  command  912-13 
REPLACE  command  914-17 
Replace  Text  (EDLIN  R)  846-47 
Report  If  Character  Ready.  See  Interrupt  I6H 
Function  OlH 

Request  header,  device  driver  452-53(fig.) 
device  open/close  464(fig.) 
flush  input/output  status  463(fig.) 
generic  lOCTL  466-67(fig.) 
get/set  logical  device  467-68(fig.) 
initialization  456(fig.) 
input/output  status  463(fig.) 
lOCTL  Read,  Write,  Write  with  Verify  46l(fig.) 
media  check  458(fig.) 
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Request  header  (continued) 
nondestructive  read  462 
removable  media  464(fig.),  464-66 
status  word  454(table) 

Reset  Alarm  (Turn  Alarm  Off).  See  Interrupt  lAH 
Function  07H 

Reset  Disk  System.  See  Interrupt  13H  Function  OOH 
Resize  Memory  Block.  See  Interrupt  21H 
Function  4AH 

Restart  System.  See  Interrupt  19H 
Restore  Backup  Files  (RESTORE)  918-22 
RESTORE  command  918-22 
ASSIGN  and  741 
BACKUP  and  745, 918 
JOIN  and  877 

RET  instruction,  terminating  .EXE  programs 
with  118-19 

Return  Address  of  InDOS  Flag.  See  Interrupt  21H 
Function  34H 

Reynolds,  Aaron,  in  development  of  MS-DOS  30, 34, 
35, 39, 43 

RMDIR/RD  command  923-24 
ROM  BASIC.  See  Interrupt  18H 
ROM  BIOS  20,  59-60 

loading  MS-DOS  and  68-72 
location  in  memory  69(fig.) 
role  in  display  I/O  159 
role  in  keyboard  I/O  156 
system  calls  1513-30  (see  also  Interrupts  lOH 
through  lAH) 
tables  69, 70(fig.) 

TSR  interrupt  processing  349 
ROM  monitor  operating  system  51 
ROOT.  ASM  program  338-42 
Root  directory  101-3 
RS232C  signals  170, 171(table) 

Run  length  limited  (RLL)  encoding  87 
Run  menu  (CodeView)  Il60 


s 

SAMPLE.C  program  (Windows)  512-17 
display  512(fig.) 

.EXE  file  construction  518-20 
header  5l6(fig.) 
make  file  517(fig.) 
message  processing  527-29 
module-definition  file  5l6-17(fig.) 
program  initialization  520-21 
resource  script  516 
source  code  513-15 
Sams,  Jack  14 


Screen.  See  also  Display  output 

ANSI.SYS  escape  sequences  to  control  731-38 
clearing  781 
controlling  158-59 
graphics  mode  (see  Graphics) 
screen  output  debugging  with  CodeView 
629-40 
swap  1055, 1150 

Scroll  Window  Down.  See  Interrupt  lOH 
Function  07H 

Scroll  Window  Up.  See  Interrupt  lOH  Function  06H 
Search  for  Text  (EDLIN  S)  848-49 
Search  Memory 

DEBUG  S 1048-49 
SYMDEB  S 1125-26 
Search  menu  (CodeView)  ll60 
Search  path 

defining  command  897 
setting  with  APPEND  739 
Seattle  Computer  Products,  and  86-DOS 12-13, 15 
Sector,  disk  88-89 
loading  1037, 1113 
writing  1052, 1136 
Seeks,  compatibility  issues  495 
Seek  to  Head.  See  Interrupt  13H  Function  OCH 
SEGDEF  Segment  Definition  object  record  651, 
676-79 

Segment.  See  Memory  segments;  Program 

segments);  Program  segment  prefix 
(PSP);  SEGMENT  directive 
SEGMENT  directive  (MASM),  to  structure  .EXE 
programs  125-30 
align  type  parameter  125-27 
class  type  parameter  128-30 
combine  type  parameter  127-28 
ordering  segments  to  shrink  .EXE  files  130 
sample  .EXE  program  using  132-37 
Segment  Not  Present  exception.  See  Interrupt  OBH 
Select  Active  Page.  See  Interrupt  lOH  Function  05H 
Select  Code  Page  function  1454-55 
Select  Color  Palette.  See  Interrupt  lOH  Function  OBH 
SELECT  command  925-29 

MS-DOS  version  3.3 1435-36 
Select  Disk.  See  Interrupt  21H  Function  OEH 
Send  Byte  to  Printer.  See  Interrupt  17H  Function  OOH 
Send  Control  Data  to  Block  Device.  See  Interrupt  21H 
Function  44H  Subfunction  05H 
Send  Control  Data  to  Character  Device.  See  Interrupt 
21H  Function  44H  Subfunction  03H 
Send  One  Character.  See  Interrupt  14H  Function  OlH 
Sequential  Read.  See  Interrupt  21H  Function  14H 
Sequential  Write.  See  Interrupt  21H  Function  15H 
Serial  communications  monitoring  556-51 
debugging  program  587-600 
demonstration  program  557-72 
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Serial  communications  ports  161-62 
configuring  892-93 
hardware  171-80 
programming  examples  l62 
Serial  Port  Services.  See  Interrupt  14H 
Servomechanism,  open  vs  closed  loop  89 
Set  Alarm  1530 

Set  Block-Device  Parameters  (DRIVPARM)  797-98 
Set  Breakpoints  (SYMDEB  BP)  1072-73 
SET  command  930-32 

AUTOEXEC.BAT  and  65, 755 
COMMAND.COM  and  65, 66, 783 
Set  Control-C  Check  (BREAK)  770-71 
Set  Country  Code  (COUNTRY)  793-94 
Set  Current  Clock  Count.  See  Interrupt  lAH 
Function  OlH 

Set  Current  Country.  See  Interrupt  21H  Function  38H 
Set  Cursor  Position.  See  Interrupt  lOH  Function  02H 
Set  Cursor  Size  and  Shape.  See  Interrupt  lOH 
Function  OlH 

Set  Data-File  Search  Path  (APPEND)  739-40 
Set  Date  (DATE)  811-12, 1268-69 
Set  Date  in  Real-Time  Clock.  See  Interrupt  lAH 
Function  05H 

Set  Device  Data.  See  Interrupt  21H  Function  44H 
Subfunction  OlH 

Set  Device  Parameters.  See  Interrupt  21H  Function 
44H  Subfunction  ODH 

Set  Disk  Type.  See  Interrupt  13H  Function  17H 
Set  Display  Mode  (MODE)  890-91 
Set  DTA  Address.  See  Interrupt  21H  Function  lAH 
Set  Environment  Variable  (SET)  930-32 
Set  Extended  Error  Information.  See  Interrupt  21H 
Function  5DH 

Set  Handle  Count  Function  1449-50 
Set  Highest  Logical  Drive  (L  ASTDRIVE)  803 
Set  Interrupt  Vector.  See  Interrupt  21H  Function  25H 
Set  Logical  Drive  Map.  See  Interrupt  21H  Function 
44H  Subfunction  OFH 
Set  Maximum  Open  Files 

using  file  control  blocks  (FCBs)  799-800 
using  handles  (FILES)  801-2 
set-mdmO  parameter  coding  222(table) 

Set  Printer  Setup.  See  Interrupt  21H  Function  5EH 
Subfunction  02H 

Set  Program  Segment  Prefix  Address.  See  Interrupt 
21H  Function  50H 

Set  Real-Time  Clock.  See  Interrupt  lAH  Function  03H 
Set  Relative  Record.  See  Interrupt  21H  Function  24H 
Set/Reset  Verify  Flag.  See  Interrupt  21H 
Function  2EH 

Set  Symbol  Value  (SYMDEB  Z)  1141-42 

Set  System  Time  (TIME)  942-43 

Set  Time.  See  Interrupt  21H  Function  2DH 


SETUP  program  942 
Set  Verify  Flag  (VERIFY)  953 
Set  Video  Mode.  See  Interrupt  lOH  Function  OOH 
SHARE  command  799, 933-34 
Shell  55, 63-68, 76-83.  See  also  COMMAND.COM 
custom  79-83 
escape  to  1154-55 
SHELL.  ASM  program  81-83 
SHELL  command  (CONFIG.SYS)  789, 804 
COMMAND.COM  and  65-66 
replacing  COMMAND.COM  with  a  custom  shell 
79-83 

SET  and  930, 931 

SHIFT  command  (BATCH)  67, 753, 754, 769 
with  GOTO  762 

Shift  Replaceable  Parameters  (SHIFT)  769 
Single  Step  exception.  See  Interrupt  OlH 
Small  memory  model  138 
SNAP.  ASM  program  359-84 

activating  the  application  382-83 
block  structure  of  381(fig.) 
code  360-80 
detecting  a  hot  key  382 
executing  383-84 
installing  381-82 
Softcard  11 

Sof  Tech  Microsystems  26 

Software.  See  also  Application  programs;  Operating 
system;  Program(s) 
in  the  development  of  MS-DOS  38 
instrumentation  debugging  555-72 
three  layers  of  447-48 
Software  Bus  86  operating  system  27 
Software  Development  Kit  (Windows)  511-12 
SORT  command  935-37 
SORT.EXE  program  442-46 
Source  code 

displaying  mode 
disabling  1128 
enabling  1127, 1129 
displaying  source  line  1151 
viewing  1134-35 
SPACE  signal  172 
Special  characters  879-81 
Kanji  and  Hangeul  37 
Specify  Command  Processor  (SHELL)  804 
SPOOLER  (Windows)  507 
Stack(s).  See  Internal  stacks 
Stack  exception.  See  Interrupt  OCH 
STACK  parameter  127-28 
STACKS  command  (CONFIG.SYS)  805 
Stand-alone  Disk  BASIC  3, 8, 12 
Stop  bits  892 

Storage  devices  85-103.  See  also  Block  device(s) 
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Storage  devices  (continued) 
block  device  layout  86-90 
file  system  layout  93-103 
partition  layout  90-92 

Strategy  routine  iStraf),  in  device  drivers  452-53 
Subdirectory  282 
copying  955 

substituting  drive  for  938 
Subroutine,  proceed  through  1043 
SUBST  command  938-39 
ASSIGN  and  741 
BACKUP  and  747 
CHKDSKand775 
DISKCOMP  and  818 
DISKCOPYand822 
FORMAT  and  866 
JOIN  and  877 
LABEL  and  882 
MKDIR/MD  and  885 
RMDIR/RD  and  923 

Substitute  Drive  for  Subdirectory  (SUBST)  938-39 
Suspend  Batch-File  Execution  (PAUSE)  766-67 
Swap  Screen  (SYMDEB  \)  1055, 1150 
Symbol 

defined  1057 
set  value  1141-42 

Symbol  file,  for  use  with  with  SYMDEB  1004-6 
Symbolic  Debugger  (SYMDEB).  1054-62  See  also 

Debugging  in  MS-DOS;  SYMDEB  utility 

Symbol  map 

examining  1138-39 
opening  1140 

SYMDEB  utility  573,  586-618, 115, 1054-62 
A  command  1063-64 
BC  command  1065-66 
BD  command  1067-68 
BE  command  1069-70 
binary  operators  1059 
BL  command  597-98,  608, 1071 
BP  command  597, 608, 1072-73 
C  command  1074 

commands  and  actions  1056-57(table) 
creating  symbol  file  for  1004 
D  command  1075-76 
DA  command  1077-78 
DB  command  1079-80 
DD  command  595,  599, 1081-82 
debugging  C  programs  with  6OO-6I8 
debugging  TSRs  with  587-600 
description  1054-61 
DL  command  1083-84 
DS  command  1085-86 
DT  command  1087-88 
DW  command  1089-90 


SYMDEB  utility  (continued) 

E  command  1091-92 
EA  command  1093-94 
EB  command  1095-96 
ED  command  1097 
EL  command  1098-99 
ES  command  1100-1101 
ET  command  1102-3 
EW  command  1104 
examples  1061-62 
F  command  1105-6 
G  command  595, 1107-8 
H  command  1109 
I  command  1110 
K  command  1111-12 
L  command  1113-14 
MAPSYM  and  1004-5 
M  command  1115 
N  command  6l4, 1116-17, 1136 
O  command  1118 
P  command  1119-20 
Q  command  595, 1121 
R  command  593, 596, 606, 1122-24 
registers  and  flags  IO6O 
S  command  1125-26 
S+  command  1127 
S-  command  1128 
S&  command  1129 
T  command  594, 598, 1130-31 
U  command  1132-33 
unary  operators  1059 
V  command  1134-35 
W  command  1136-37 

X  command  594,  596,  598-99, 606, 607, 6l3, 6l4, 
1138-39 

XO  command  598, 6l2, 1140 
Z  command  598, 6l2, 1141-42 
<  command  1143-44 
>  command  1145 
=  command  1146 
{ command  1147 
}  command  1148 
~  command  1149 
\  command  1150 
.  command  1151 
?  command  1152-53 
!  command  1154-55 
•  command  1156 

SYS  command  940-41 
ASSIGN  and  741 

SYSINIT  61, 73-76 

System  batch-file  interpreter  (BATCH)  752-69 

System  calls,  MS-DOS  1177-84.  See  also  Interrupts 
2m  throughlPH 
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System  calls  (continued) 

arranged  by  functional  group  1181-84 
format  1178-81 
PC  ROM  BIOS  1513-30 
version  differences  1177-78 
System  configuration  and  control  commands  728 
BREAK  770-71 
COMMAND  782-84 
DATE  811-12 
EXIT  853 
PROMPT  904-6 
SELECT  925-29 
SET  930-32 
SHARE  933-34 
TIME  942-43 
VER952 

System  Configuration  File  (CONFIG.SYS)  788-89 
System  configuration  file  directives  729-30, 788-89 
BREAK  790 
BUFFERS  791-92 
COUNTRY  793-94 
DEVICE  795-96 
DRIVPARM  797-98 
FCBS  799-800 
FILES  801-2 
LASTDRIVE803 
SHELL  804 
STACKS  805 

System  Startup  Batch  File  (AUTOEXEC.BAT)  755-57 


T 

Tandy  2000  computer  34 
Tape  drive  storage  103 
Template,  editing  buffer  832 
TEMPLATE. ASM  character-device  driver  471-78 
TERMINAL  dialog  box  (Windows)  505(fig.) 
Terminal  emulator  CTERM.C  230-46 
Terminate  and  Stay  Resident.  See  Interrupt  21H 
Function  31H;  Interrupt  27H 
Terminate-and-stay-resident  utilities  347-84.  See 
also  Interrupt  21H  Function  31H; 
Interrupt  27H 

APPEND  command  iy)-4i0 
building  instrumentation  software  for 
debugging  with  556-72 
determining  MS-DOS  status  353-56 
multiplex  interrupt  356-57 
organization  in  memory  348(fig.) 
programming  examples  357-81 
HELLO.  ASM  357-59 
SNAP.  ASM  359-81 
segment  order  for  713-14 


Terminate-and-stay-resident  utilities  (continued) 
structure  of  275-349 
system  calls  for  350-53 
using  SYMDEB  to  debug  587-600 
Terminate  Command  Processor  (EXIT)  853 
Terminate  Process.  See  Interrupt  21H  Function  OOH 
Terminate  Process  with  Return  Code.  See  Interrupt 
21H  Function  4CH 

Terminate  Program.  See  Interrupt  20H 
Terminate  Routine  Address.  See  Interrupt  22H 
TESTCOMM.  ASM  programs  544 
corrected  code  580-81 
incorrect  code  574-75 

Test  for  Drive  Ready.  See  Interrupt  13H  Function  lOH 
Text  and  files  (Windows)  536 
Text  editor,  escape  sequences  in  732.  See  also  EDLIN 
commands 

THEADR  Translator  Header  object  record  651, 657 

TIME  command  942-43 

Timer 

setting  date  811 
setting  time  942 

Timer  Tick  (user  defined).  See  Interrupt  ICH 
Time-slicing  900 

TINYDISK.  ASM  block-device  driver  478-86 
Torode,  John  10 
Trace  Program  Execution 
DEBUG  T 1050 
SYMDEB  T 1130-31 
Tracks,  disk  87, 88(fig.) 

Traf-O-Data  machine  5-6 
Transfer  Another  File  (EDLIN  T)  850-51 
Transfer  Control  to  ROM-BASIC.  See  Interrupt  18H 
Transfer  System  Files  (SYS)  940-41 
Transient  program  area  (TPA)  79 

in  conventional  memory  298-99 
TREE  command  944-46 
TSR.  See  Terminate-and-stay-resident  utilities 
TYPDEF  Type  Definition  object  record  651, 665-68 
TYPE  command  947 

escape  sequences  using  732 


u 

UART.  See  INS8250  Universal  Asynchronous  Receiver 
Transmitter  (UART) 

Ulloa,  Mani34,37 
Unary  operators,  SYMDEB  1059 
Un filtered  Character  Input  Without  Echo.  See 
Interrupt  21H  Function  07H 
UNIX  operating  system  68 
directories  284 
file  management  30 
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Update  Files  (REPLACE)  914-17 
UPPERCAS.C  programs  545 
correct  code  629(fig.) 
correction  of  620 - 29 
incorrect  620(fig.) 


V 

VDISK.SYS  948-51 
VER  command  952 
VERIFY  command  953 

Verify  Disk  Sectors.  See  Interrupt  13H  Function  04H 
Verify  flag,  set  953 

Verify  Track  on  Logical  Drive.  See  Interrupt  21H 
Function  44H  Subfunction  ODH 
Version,  display  952 
Victor  Corporation  35 

Video.  See  Character-device  input/output;  Display 
output;  Screen 

Video  Graphics  Array  (VGA)  157 
Video  Parameter  Pointer.  See  Interrupt  IDH 
Video  Services.  See  Interrupt  lOH 
View  menu  (CodeView)  1160 
View  Source  Code  (SYMDEB  V)  1134-35 
Virtual  Disk  (RAMDRIVE.SYS)  907-9 
Virtual  Disk  (VDISK.SYS)  948-51 
VOL  command  954 
Volume  labeKs)  103,  283-84 
displaying  954 
modifying  882 

program  example  for  updating  292-96 


w 

Wallace,  Bob  8(fig.) 

Warm  boot  68 

Warm  Boot/Terminate  vector  117-18 
Watch  menu  (CodeView)  ll6l 
Watchpoints  6l9 
Wildcard(s) 

COPY  806 
DEL/ERASE  813 
DIR  816 

directory  searches  286-87 
REPLACE  914 
RESTORE  918 

Window-Oriented  Debugger  (CodeView).  1157-73 
See  also  CodeView  utility;  Debugging 
in  MS-DOS 


Windows  499-538 

application  and  utility  programs  in  506-7 
data  sharing/data  exchange 
Clipboard  537-38 
dynamic  data  exchange  538 
display  500-505 

dialog  boxes  504-5 
parts  of  the  window  501-4 
graphics  device  interface  529-37 
internationalization  538 
memory  management  510-11 
MS-DOS  Executive  505,  506(fig.) 
multitasking  529 
new  executable  header  1487-97 
program  categories  499-500 
structure  of  507-10 

libraries  and  programs  509-10 
modules  507-9 
structure  of  a  program  511-29 
message  processing  525-26 
message  processing  example  527-29 
messages  524-25 
messaging  system  522-24 
program  components  512-17 
program  construction  518-20 
program  initialization  520-21 
software  development  kit  511-12 
Wood,  Marla  8(fig.) 

Wood,  Steve  8(fig.) 

Word(s),  16-bit  172,  222 
displaying  1089-90 
entering  1104 
WORD  alignment  126 
Wrap  around,  screen  display  733 
Write  Character  and  Attribute.  See  Interrupt  lOH 
Function  09H 

Write  Character  as  TTY.  See  Interrupt  lOH 
Function  OEH 

Write  Character  Only.  See  Interrupt  lOH 
Function  OAH 

Write  Character  String.  See  Interrupt  lOH 
Function  13H 

Write  Data  to  Cassette.  See  Interrupt  15H 
Function  03H 

Write  Disk  Sectors.  See  Interrupt  13H  Function  03H 
Write  File  or  Device.  See  Interrupt  21H 
Function  40H 
Write  File  or  Sectors 

DEBUG  W  586-87, 1052-53 
SYMDEB  W 1136-37 
Write  Lines  to  Disk  (EDLIN  W)  852 
Write  Long.  See  Interrupt  13H  Function  OBH 
Write  Pixel  Dot.  See  Interrupt  lOH  Function  OCH 
Write  Track  on  Logical  Drive.  See  Interrupt  21H 
Function  44H  Subfunction  ODH 
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Subject 


X 


z 


XCOPY  command  955-59 
ATTRIBand743 
DISKCOPYand822 
XENIX  operating  system  30, 31, 68 
directories  284 
XON/XOFF168 


Zbikowski,  Mark,  in  the  development  of  MS-DOS  30, 
34,35,37,39,43 
Z-DOS  operating  system  27 
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Commands  and  System  Calls 

This  index  lists  only  primary  command  and  system  call  entries.  Please  use  the  Subject  Index for  related  entries. 


SYMBOLS 

©(BATCH)  1434 


A 

ANSI.SYS  731-38 
APPEND  739-40, 1436-37 
ASSIGN  741-42 
ATTRIB  743-44, 1437 
AUTOEXEC.BAT  (BATCH)  755-57 


B 

BACKUP 745-51, 1437 
BATCH  752-69, 1434-35 
BREAK  770-71 
BREAK  (CONFIG.SYS)  790 
BUFFERS  (CONFIG.SYS)  791-92 


c 

CALL  (BATCH)  1434-35 
CD  772-73 
CHCP1440 
CHDIR  772-73 
CHKDSK  774-80 
CLS781 

OxleView  utility  1157-73 
COMMAND  782-84 
COMP  785-87, 1435 
CONFIG.SYS  788-805 
COPY  806-9 

COUNTRY  (CONFIG.SYS)  793-94, 1442-43 

CREF  utility  967-70 

CTTY810 


D 

DATE  811-12 
DEBUG,  general  1020-23 
DEBUG  utility  1020-53 
A  command  1024-25 
C  command  1026 
D  command  1027-28 
E  command  1029-30 
F  command  1031-32 
G  command  1033-34 
H  command  1035 
I  command  1036 
L  command  1037-38 
M  command  1039 
N  command  1040-41 
O  command  1042 
P  command  1043 
Q  command  1044 
R  command  1045-47 
S  command  1048-49 
T  command  1050 
U  command  1051 
W  command  1052-53 
DELETE  813-14 

DEVICE  (CONFIG.SYS)  795-96, 1443-45 

DIR  815-17 

DISKCOMP  818-21 

DISKCOPY  822-25 

DRIVER.SYS  826-28 

DRIVPARM  (CONFIG.SYS)  797-98 


E 

ECHO  (BATCH)  758-59 
EDLIN,  general  829-31 
EDLIN  line  editor  829-52 
A  command  834 
C  command  835-36 
D  command  837-38 
E  command  839 
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EDLIN  line  editor  (continued) 

I  command  840 
L  command  841 
linenumber  command  832-33 
M  command  842-43 
P  command  844 
Q  command  845 
R  command  846-47 
S  command  848-49 
T  command  850-51 
W  command  852 
ERASE  813-14 
EXE2BIN  utility  971-73 
EXEMOD  utility  974-76 
EXEPACK  utility  977-79 
EXIT  853 


F 

FASTOPEN 1433-34 
FC  854-57 

FCBS  (CONFIG.SYS)  799-800 
FDISK  858-62, 1437 
FILES  (CONFIG.SYS)  801-2 
FIND  863-64 
FOR  (BATCH)  760-61 
FORMAT  865-71 


G 

GOTO  (BATCH)  762-63 
GRAFTABL  872-73, 1445 
GRAPHICS  874-76 


I 

IF  (BATCH)  764-65 
Interrupt  lOH,  Video  Services  1513-18 
Function  OOH,  Set  Video  Mode  1513 
Function  OlH,  Set  Cursor  Size  and  Shape  1514 
Function  02H,  Set  Cursor  Position  1514 
Function  03H,  Read  Cursor  Position,  Size,  and 
Shape  1514 

Function  04H,  Read  Light-Pen  Position  1514-15 
Function  05H,  Select  Active  Page  1515 
Function  06H,  Scroll  Window  Up  1515 
Function  07H,  Scroll  Window  Down  1515 


Interrupt  lOH  (continued) 

Function  08H,  Read  Character  and  Attribute  at 
Cursor  1515-16 

Function  09H,  Write  Character  and  Attribute 
1516 

Function  OAH,  Write  Character  Only  1516 
Function  OBH,  Select  Color  Palette  1516 
Function  OCH,  Write  Pixel  Dot  1517 
Function  ODH,  Read  Pixel  Dot  1517 
Function  OEH,  Write  Character  as  TTY  1517 
Function  OFH,  Get  Current  Video  Mode  1517 
Function  13H,  Write  Character  String  1518 
Interrupt  IIH,  Get  Peripheral  Equipment  List  1518 
Interrupt  12H,  Get  Usable  Memory  Size  (KB)  1519 
Interrupt  13H,  Disk  Services  1519-23 

Function  OOH,  Reset  Disk  System  1519 
Function  OlH,  Get  Disk  Status  1519-20 
Function  02H,  Read  Disk  Sectors  1520 
Function  03H,  Write  Disk  Sectors  1520 
Function  04H,  Verify  Disk  Sectors  1520 
Function  05H,  Format  Disk  Tracks  1520 
Function  08H,  Get  Current  Drive  Parameters 
1520-21 

Function  09H,  Initialize  Hard-Disk  Parameter 
Table  1521 

Function  OAH,  Read  Long  1521 
Function  OBH,  Write  Long  1521 
Function  OCH,  Seek  to  Head  1521 
Function  ODH,  Alternate  Disk  Reset  1522 
Function  lOH,  Test  for  Drive  Ready  1522 
Function  IIH,  Recalibrate  Drive  1522 
Function  14H,  Controller  Diagnostic  1522 
Function  15H,  Get  Disk  Type  1522-23 
Function  16H,  Check  for  Change  of  Floppy-Disk 
Status  1523 

Function  17H,  Set  Disk  Type  1523 
Interrupt  14H,  Serial  Port  Services  1523-25 
Function  OOH,  Initialize  Port  Parameters 
1523-24 

Function  OlH,  Send  One  Character  1524 
Function  02H,  Receive  One  Character  1524 
Function  03H,  Get  Port  Status  1524-25 
Interrupt  15H,  Miscellaneous  System  Services 
1525-26 

Function  OOH,  Turn  On  Cassette  Motor  1525 
Function  OlH,  Turn  Off  Cassette  Motor  1525 
Function  02H,  Read  Data  from  Cassette  1525-26 
Function  03H,  Write  Data  to  Cassette  1526 
Interrupt  16H,  Keyboard  Services  1526-27 
Function  OOH,  Read  Next  Character  1526 
Function  OlH,  Report  If  Character  Ready  1527 
Function  02H,  Get  Shift  Status  1527 
Interrupt  17H,  Printer  Services  1527-28 
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Interrupt  17H  (continued) 

Function  OOH,  Send  Byte  to  Printer  1527 
Function  OlH,  Initialize  Printer  1528 
Function  02H,  Get  Printer  Status  1528 
Interrupt  18H,  Transfer  Control  to  ROM-BASIC  1528 
Interrupt  19H,  Reboot  Computer  (Warm  Start)  1528 
Interrupt  lAH,  Get  and  Set  Time  1528-30 

Function  OOH,  Read  Current  Clock  Count 

1528- 29 

Function  OlH,  Set  Current  Clock  Count  1529 
Function  02H,  Read  Real-Time  Clock  1529 
Function  03H,  Set  Real-Time  Clock  1529 
Function  04H,  Read  Date  from  Real-Time  Clock 

1529- 30 

Function  05H,  Set  Date  in  Real-Time  Clock  1530 
Function  06H,  Set  Alarm  1530 
Function  07H,  Reset  Alarm  (Turn  Alarm  Off) 
1530 

Interrupt  20H,  Terminate  Program  1185-86 
Interrupt  21H,  MS-DOS  function  calls  1187-1416 
Function  OOH,  Terminate  Process  1187-88 
Function  OlH,  Character  Input  with  Echo 
1189-90 

Function  02H,  Character  Output  1191-92 
Function  03H,  Auxiliary  Input  1193-94 
Function  04H,  Auxiliary  Output  1195-96 
Function  05H,  Print  Character  1197-98 
Function  06H,  Direct  Console  I/O  1199-1200 
Function  07H,  Unfiltered  Character  Input 
Without  Echo  1201-2 

Function  08H,  Character  Input  Without  Echo 
1203-4 

Function  09H,  Display  String  1205-6 
Function  OAH,  Buffered  Keyboard  Input  1207-8 
Function  OBH,  Check  Keyboard  Status  1209-10 
Function  OCH,  Flush  Buffer,  Read  Keyboard 
1211-12 

Function  ODH,  Disk  Reset  1213-14 
Function  OEH,  Select  Disk  1215-16 
Function  OFH,  Open  File  with  FCB 1217-19 
Function  lOH,  Close  File  with  FCB  1220-21 
Function  IIH,  Find  First  File  1222-24 
Function  12H,  Find  Next  File  1225-26 
Function  13H,  Delete  File  1227-28 
Function  14H,  Sequential  Read  1229-30 
Function  15H,  Sequential  Write  1231-32 
Function  16H,  Create  File  with  FCB  1233-34 
Function  17H,  Rename  File  1235-36 
Function  19H,  Get  Current  Disk  1237 
Function  lAH,  Set  DTA  Address  1238-39 
Function  IBH,  Get  Default  Drive  Data  1240-41 
Function  ICH,  Get  Drive  Data  1242-44 
Function  21H,  Random  Read  1245-46 
Function  22H,  Random  Write  1247-48 


Interrupt  21H  (continued) 

Function  23H,  Get  File  Size  1249-50 
Function  24H,  Set  Relative  Record  1251-52 
Function  25H,  Set  Interrupt  Vector  1253-54 
Function  26H,  Create  New  Program  S^ment 
Prefix  1255-56 

Function  27H,  Random  Block  Read  1257-59 
Function  28H,  Random  Block  Write  1260-62 
Function  29H,  Parse  Filename  1263-65 
Function  2AH,  Get  Date  1266-67 
Function  2BH,  Set  Date  1268-69 
Function  2CH,  Get  Time  1270-71 
Function  2DH,  Set  Time  1272-73 
Function  2EH,  Set/Reset  Verify  Flag  1274-75 
Function  2FH,  Get  DTA  Address  1276 
Function  30H,  Get  MS-DOS  Version  Number 
1277-78 

Function  31H,  Terminate  and  Stay  Resident 
1279-80 

Function  33H,  Get/Set  Control-C  Check  Flag 
1281-82 

Function  34H,  Return  Address  of  InDOS  Flag 
1283 

Function  35H,  Get  Interrupt  Vector  1284 
Function  36H,  Get  Disk  Free  Space  1285-86 
Function  38H,  Get/Set  Current  Country  1287-90 
Get  Current  Country  1287-89 
Set  Current  Country  1290 
Function  39H,  Create  Directory  1291-92 
Function  3AH,  Remove  Directory  1293-94 
Function  3BH,  Change  Current  Directory 
1295-96 

Function  3CH,  Create  File  with  Handle  1297-99 
Function  3DH,  Open  File  with  Handle 
1300-1303 

Function  3EH,  Close  File  1304-5 
Function  3FH,  Read  File  or  Device  1306-7 
Function  40H,  Write  File  or  Device  1308-9 
Function  41H,  Delete  File  1310-11 
Function  42H,  Move  File  Pointer  1312-14 
Function  43H,  Get/Set  File  Attributes  1315-16 
Function  44H,  lOCTL  1317-18 

Subfunction  OOH,  Get  Device  Data  1319-21 
Subfunction  OlH,  Set  Device  Data  1322-23 
Subfunction  02H,  Receive  Control  Data  from 
Character  Device  1324-25 
Subfunction  03H,  Send  Control  Data  to 
Character  Device  1324-25 
Subfunction  04H,  Receive  Control  Data  from 
Block  Device  1326-28 
Subfunction  05H,  Send  Control  Data  to 
Block  Device  1326-28 
Subfunction  06H,  Check  Input  Status 
1329-30 


Indexes  1567 


Commands  and  System  Calls 


Interrupt  21H  (continued) 

Function  44H  (continued) 

Subfunction  07H,  Check  Output  Status 
1329-30 

Subfunction  OSH,  Check  If  Block  Device  Is 
Removable  1331-32 

Subfunction  09H,  Check  If  Block  Device  Is 
Remote  1333-34 

Subfunction  OAH,  Check  If  Handle  Is 
Remote  1335-36 

Subfunction  OBH,  Change  Sharing  Retry 
Count  1337-38 

Subfunction  OCH,  Generic  I/O  Control  for 
Handles  1339-40, 1455-58 
Subfunction  ODH,  Generic  I/O  Control  for 
Block  Devices  1341-42 
Subfunction  ODH,  minor  code  40H,  Set 
Device  Parameters  1343-46 
Subfunction  ODH,  minor  code  41H,  Write 
Track  on  Logical  Drive  1350-51 
Subfunction  ODH,  minor  code  42H,  Format 
and  Verify  Track  on  Logical  Drive 
1352-53 

Subfunction  ODH,  minor  code  60H,  Get 
Device  Parameters  1347-49 
Subfunction  ODH,  minor  code  6lH,  Read 
Track  on  Logical  Drive  1350-51 
Subfunction  ODH,  minor  code  62H,  Verify 
Track  on  Logical  Drive  1352-53 
Subfunction  OEH,  Get  Logical  Drive  Map 
1354-55 

Subfunction  OFH,  Set  Logical  Drive  Map 
1354-55 

Function  45H,  Duplicate  File  Handle  1356-57 
Function  46H,  Force  Duplicate  File  Handle 
1358-59 

Function  47H,  Get  Current  Directory  1360-61 
Function  48H,  Allocate  Memory  Block  1362-63 
Function  49H,  Free  Memory  Block  1364-65 
Function  4AH,  Resize  Memory  Block  1366-67 
Function  4BH,  Load  and  Execute  Program 
(EXEC)  1368-74 

Function  4CH,  Terminate  Process  with  Return 
Code  1375-76 

Function  4DH,  Get  Return  Code  of  Child 
Process  1377-78 

Function  4EH,  Find  First  File  1379-81 
Function  4FH,  Find  Next  File  1382-84 
Function  54H,  Get  Verify  Flag  1385 
Function  56H,  Rename  File  1386-87 
Function  57H,  Get/Set  Date/Time  of  File 
1388-90 

Function  58H,  Get/Set  Allocation  Strategy 
1391-92 


Interrupt  21H  (continued ) 

Function  59H,  Get  Extended  Error  Information 
1393-96 

Function  5AH,  Create  Temporary  File  1397-98 
Function  5BH,  Create  New  File  1399-1400 
Function  5CH,  Lock/Unlock  File  Region 
1401-3 

Function  5EH,  Network  Machine  Name/Printer 
Setup  1404-6 

Subfunction  OOH,  Get  Machine  Name  1404 

Subfunction  02H,  Set  Printer  Setup  1405-6 

Subfunction  03H,  Get  Printer  Setup  1405-6 
Function  5FH,  Get/Make  Assign-List  Entry 
1407-12 

Subfunction  02H,  Get  Assign-List  Entry 
1407-8 

Subfunction  03H,  Make  Assign-List  Entry 
1409-10 

Subfunction  04H,  Cancel  Assign-List  Entry 
1411-12 

Function  62H,  Get  Program  Segment  Prefix 
Address  1413-14 

Function  63H,  Get  Lead  Byte  Table  1415-16 
Function  65H,  Get  Extended  Country 
In  formation  1451  -  54 
Function  66H,  Select  Code  Page  1454-55 
Function  67H,  Set  Handle  Count  1449-50 
Function  68H,  Commit  File  Function  1450-51 
Interrupt  22H,  Terminate  Routine  Address  1417 
Interrupt  23H,  Control-C  Handler  Address  1418 
Interrupt  24H,  Critical  Error  Handler  Address  1419-21 
Interrupt  25H,  Absolute  Disk  Read  1422-23 
Interrupt  26H,  Absolute  Disk  Write  1424-25 
Interrupt  27H,  Terminate  and  Stay  Resident  1426-27 
Interrupt  2FH,  Multiplex  Interrupt  1428-29 


J,k,l 

JOIN  877-78 
KEYS  1440-41 
KEYBxx  879-81 
LABEL  882-84 

LASTDRIVE  (CONFIG.SYS)  803 
LIB  utility  980-86 
LINK  utility  987-98 


M 

MAKE  utility  999-1003 
MAPSYM  utility  1004-6 


1568  The  MS-DOS  Encyclopedia 


Commands  and  System  Calls 


MASM  utility  1007-19 
MD  885-86 
MKDIR  885-86 
MODE  887-95, 1446-47 
MORE  896 


N,P 

NLSFUNC 1441-42 
PATH  897-98 
PAUSE  (BATCH)  766-67 
PRINT  899-903 

Programming  Utilities  (Introduction)  963-65 
PROMPT  904-6 


R 

RAMDRIVE.SYS907->9 
RD  923-24 
RECOVER  910-11 
REM  (BATCH)  768 
REN  912-13 
RENAME  912-13 
REPLACE  914-17 
RESTORE  918-22 
RMDIR  923-24 


s 

SELECT  925-29, 1435-36 
SET  930-32 
SHARE  933-34 
SHELL  (CONFIG.SYS)  804 
SHIFT  (BATCH)  769 
SORT  935-37 

STACKS  (CONFIG.SYS)  805 
SUBST  938-39 
SYMDEB,  general  1054-62 
SYMDEB  utility  1054-1156 
A  command  1063-64 
BC  command  1065-66 
BD  command  1067-68 
BE  command  1069-70 
BL  command  1071 
BP  command  1072-73 
C  command  1074 
D  command  1075-76 


SYMDEB  utility  (continued) 

DA  command  1077-78 
DB  command  1079-80 
DD  command  1081-82 
DL  command  1083-84 
DS  command  1085-86 
DT  command  1087-88 
DW  command  1089-90 
E  command  1091-92 
EA  command  1093-94 
EB  command  1095-96 
ED  command  1097 
EL  command  1098-99 
ES  command  1100-1101 
ET  command  1102-3 
EW  command  1104 
F  command  1105-6 
G  command  1107-8 
H  command  1109 
I  command  1110 
K  command  1111-12 
L  command  1113-14 
M  command  1115 
N  command  1116-17 
O  command  1118 
P  command  1119-20 
Q  command  1121 
R  command  1122-24 
S  command  1125-26 
S+  command  1127 
S-  command  1128 
S&  command  1129 
T  command  1130-31 
U  command  1132-33 
V  command  1134-35 
W  command  1136-37 
X  command  1138-39 
XO  command  1140 
Z  command  1141-42 
<  command  1143-44 
>  command  1145 
=  command  1146 
{ command  1147 
}  command  1148 
~  command  1149 
\  command  1150 
.  command  1151 
?  command  1152-53 
!  command  1154-55 
•  command  1156 

SYS  940-41 

System  Calls  (Introduction)  1177-84 
format  of  entries  1178-81 
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System  Calls  (continued) 

by  functional  group  1181-84 
version  differences  1177-'78 


T,U 

TIME  942-43 
TREE  944-46 
TYPE  947 

User  Commands  (Introduction)  725-30 
by  functional  group  728-30 
key  to  entries  726-27 


V,x 

VDISK.SYS  948-51 
VER952 
VERIFY  953 
VOL  954 
XCOPY  955-59 
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will  not  want  to  be  without  [THE 
MS-DOS  ENCYCLOPEDIA].” 

Online  Today 

“The  ultimate  authority.” 

Reference  &  Research  Book  News 

“A  splendid  volume.” 

Dr,  Dobh^s  Journal  of  Software  Tools 


“For  those  with  any  technical  in¬ 
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